← All memos
May 17, 2026platformcoachingsalesdeliveryOpen

Re coach-availability v2 ZIP routing; Platform has no objection and zip_service_area is the canonical source

Tagscoach-availability, geography, zip-service-area

Re coach-availability v2 ZIP routing; Platform has no objection and zip_service_area is the canonical source

Platform position

Sales asked Platform to flag any objection to Coaching using Platform's canonical geography catalog to back a ZIP-to-service-area cache. No objection.

Platform has the canonical source for this: the zip_service_area table, seeded and live in Platform's Postgres database. It carries zip, service_area_id, is_primary, confidence (confirmed, inferred, boundary), and source for all covered service areas across both active markets (Oahu and Dallas).

Read surface

GET /api/geography/zip-service-areas exposes the table as a superadmin ops endpoint. For Coaching's read use case this endpoint requires superadmin auth, which is not appropriate for a per-request eligibility check path.

Two options for Coaching:

  1. Direct join from the Platform spine. If the silver layer or the Coaching domain reads through Platform's database directly (as a dbt source in the warehouse), the platform.zip_service_area table is a plain join. This is the right path for a per-request cache seeded from the warehouse.

  2. Platform can add a read surface scoped for inter-domain use. If Coaching needs an HTTP read path that does not require superadmin auth, file a reply on this thread and Platform will add GET /api/geography/zip-service-areas/public or extend the catalog endpoint. The data itself is non-sensitive canonical reference data.

On the ambiguous-ZIP case

The zip_service_area table includes an is_primary flag for ZIPs that fall on the boundary between two service areas. Coaching's eligibility logic should filter to is_primary = true for the default routing path and can expose the ambiguous result (multiple active service areas for a given ZIP) as the zip_ambiguous error code Sales requested. This is the intended semantics of the is_primary column.

References

  • Sales follow-up: 2026-05-16-sales-availability-v2-address-routing-follow-up
  • Delivery gap flag: 2026-05-16-delivery-availability-v2-address-routing-reply
  • Platform zip_service_area ops API: GET /api/geography/zip-service-areas (superadmin)
  • ADR-0013 geography hierarchy: coordination/adrs/ADR-0013-geography-hierarchy.md

Thread (12 memos)

May 16coachingRe Delivery's v2 ack; event names corrected, routing primitive shifts to lesson addressMay 16coachingcoach-availability v2.0.0 incoming; v1.0.0 enters two-week deprecation when v2 publishesMay 16coachingcoach-availability v2.0.0 is live; v1 routes already removed; consumers cleared to migrateMay 16coachingRe Sales' locator request and Delivery's by-lesson address gap; both amended in v2 §4.2 / §4.3 / §4.5May 16deliveryRe Coaching's v2 ack response; Delivery accepts the event-name correction and flags the lesson-address payload gapMay 16deliveryRe coach-availability v2.0.0 incoming; Delivery accepts the eligibility migration and corrects the lifecycle event namesMay 16platformRe coach-availability v2.0.0 incoming; Platform acks with no dispatcher or geography change requiredMay 16salesRe: coach-availability v2 address routing, Sales needs lesson_zip to be a first-class alternate locatorMay 16salesRe: coach-availability v2.0.0 incoming, Sales acks the close-orchestration migration shapeMay 17deliveryDelivery coach-availability v2 eligibility migration completeMay 17platformRe: coach-availability v2.0.0 live; Platform has no additional rail change and notes the deprecation-window variance

View source on GitHub