← All memos
Apr 28, 2026delivery→platformResponded

ADR-0007 proposal — org-scoped Configs are opt-in

Response byMay 12, 2026
Tagsadr, schema, master-schema, delivery, airtable

ADR-0007 proposal — org-scoped Configs are opt-in

Date: 2026-04-28 From: Delivery To: Platform (acknowledgment); Sales and Revenue informational Status: Proposed. Two-week comment window through 2026-05-12, then Delivery moves to apply.

Why

The Master Schema documents a two-tier shape: global identity records at the top (Lesson Sites, Service Areas, Markets, Clients, Students, Coaches, Organizations), org-scoped operational records one tier down (Lesson Site Configs, Service Area Configs, Lesson Types, the Profiles family). Most readers infer that every global identity record gets a Configs partner. Two facts undercut that inference: Markets has never had a Market Configs partner, and Service Area Configs has been sitting almost empty for over a year — the substantive payload is a coach-coverage list and a derived-geography forwarding link, neither of which justifies a domain entity. The asymmetry is currently undocumented, which means the next contributor to add a global identity record will either pre-create an empty Configs slot prophylactically or reopen the same debate.

This memo accompanies a proposed ADR (ADR-0007) that makes the rule explicit: Configs slots earn their place by holding org-scoped payload that does not fit naturally on any other org-scoped entity. The application that triggered the proposal is collapsing Service Area Configs and attaching Service Area and Market directly to Lesson Site at the global tier.

What

The ADR has the full case. A short summary for the inbox view:

The rule is that the Org-Scoped Operational Context tier is opt-in, not mandatory. A Configs slot is created or kept only when it carries org-scoped fields that would not fit on Coach Profile, Client Profile, Student Profile, Lesson Type, or another existing org-scoped table. Empty or near-empty Configs slots are not preserved in anticipation of payload that has not landed.

The application of the rule is that Service Area Configs is collapsed. Service Area becomes a direct multi-link on Lesson Site (geography is global) and a multi-link on Coach Profile (coverage is per-coach, scoped via Coach Profile's existing per-org shape). Market becomes a direct multi-link on Lesson Site, parallel to Service Area; no Market Configs is introduced. Lesson Site Configs.Service Area Config is dropped as derivable through the new global edge. Lesson Site Configs is otherwise unchanged. The Lesson.Lesson Site Config edge is unchanged in every option, so no Lesson reads or Org Mismatch checks move.

The blast radius is one Airtable table archival, one link backfill on Coach Profiles (existing Service Area Config ↔ Coach Profile data into Coach Profile.Service Areas), and a few legacy views that show Service Area through the Lesson Site Config indirection. The Q2 scheduling migration off Airtable to Postgres benefits because the Postgres-native schema does not need to recreate Service Area Configs.

Asks

For Platform: an acknowledgment on this memo, since the Master Schema is a Platform-shaped reference doc and the rule statement is a pattern claim that other domains will read. No sign-off required. If the rule reads as a Platform decision rather than a Delivery one, say so and we will refile under Platform with Delivery as the primary applicant.

For Sales and Revenue: FYI. Sales because Coach Profile gets a new Service Areas field that may eventually inform lead routing if you want it to; you do not need to consume it now. Revenue because you sometimes consume Delivery-owned tables for cross-domain rollups; the schema change is internal to Delivery's tier and the Lesson.Lesson Site Config edge is unchanged, so no Revenue reads should move. Flag if you see a path I missed.

If no objections by 2026-05-12, Delivery moves to apply: add the new global-tier links, backfill Coach Profile.Service Areas, drop the Lesson Site Configs.Service Area Config field, archive Service Area Configs, update the Master Schema page, and file Change Log entries on the affected schema pages.

References

Thread (2 memos)

Apr 28platformRe: ADR-0007 proposal — org-scoped Configs are opt-in

View source on GitHub