Memo: Notion-canonical schema management for Airtable bases

Date: 2026-04-27 From: Revenue To: Platform Status: Procedural changes adopted in the CL-REV-0001 (GAAP revenue recognition) working session. Notion structure already live. Four asks for Platform at the bottom; three need a Platform-owned changeset, one is informational.

Purpose

This memo documents three things that changed during the CL-REV-0001 working session that are not Revenue-specific. They affect every domain that owns tables in the Airtable base app1K2d9GZVsE7vWh (display name: Operations — legacy from before the Delivery rename), not just Revenue. They are filed under Platform because Platform owns the Schema Change Process and the cross-domain reference docs the changes touch.

The headline: snapshots no longer dump the whole base; they slice per-table; per-table history attaches to each table's Notion schema page. This decouples the eventual rebuild-out-of-Airtable codebase from any Airtable-era artifact, by keeping all Airtable schema metadata in Notion rather than in a code repo.

Why decouple Airtable from the repos at all

The eventual rebuild path exits Airtable entirely. Each domain rebuilds its own services and schemas in code, with Person identity and tenancy on Platform per ADR-0001 and ADR-0002, and the Person/Participant split per ADR-0003. When that rebuild starts, the Airtable schema is no longer relevant — it was a substrate, not a contract. Anything that lives in a code repo today and references Airtable shape (a snapshot, a field-name dump, a JSON export of base metadata) becomes dead weight at best and a confusing red herring at worst, because the new code's schema will not look like the legacy Airtable shape and developers reading the repo should not be primed to expect it to.

Notion is already the source of truth for schema shape per Tier 1 of the Schema Change Process. The natural extension is to treat Notion as the canonical home for the artifacts that document schema shape too — snapshots, change logs, the manifest of which table belongs to which domain. The repos stay focused on domain logic, contract definitions, and tests. Airtable lives entirely upstream of code, and its history lives entirely in Notion.

This is a codification of intent that has been implicit. The new procedures put structure behind it, and the structure is enforceable: a snapshot file in a repo is an immediate signal that the rule has been violated and should be moved to Notion or deleted.

What changed

Per-table snapshots, not base-wide

Tier 2 of the Schema Change Process said: dump the full base schema as JSON before and after every changeset, save to a Drive folder or GitHub repo. The new procedure: dump per-table, only for tables the changeset actually touches, and attach the JSON to each table's own Notion schema page in a ## Schema Snapshots section.

A typical changeset modifies one to five tables out of forty-three. Base-wide dumps include thirty-eight tables that did not change and that no one will inspect when investigating that changeset. Per-table snapshots bound the noise to exactly the surface area that matters. Cross-changeset diffs for a single table become trivial — open the table's schema page, attach two snapshots, run diff on the downloaded files. Cross-table diffs for a single changeset become a fan-out across the touched tables' pages, which is fine because that fan-out matches the unit of investigation (you almost always want "what changed in Lessons" or "what changed for CL-REV-0001"; you almost never want "what changed in the entire base on 2026-04-27").

Two artifacts per changeset per touched table: a pre snapshot of the state before application, and a post snapshot of the state after. New tables created by a changeset have no pre — they did not exist; their snapshot history starts at post.

The snapshot JSON is pretty-printed, sorted alphabetically by table and then by field name within each table, and wrapped with a small provenance header (base_id, captured_at, changeset, phase, table_name, field_count, sliced_at). Sort and wrapper exist so that diffs across versions read field-by-field rather than as a noisy whole-file replacement.

Weekly cadence skipped, with intent to revive when automated

Tier 2's weekly snapshot was a defense against drift from un-changeset-numbered Airtable edits — the things that should not have happened but did. With per-table snapshots writing on every changeset, evidence of every intentional change exists; drift would now show up as an Airtable change with no corresponding snapshot or Change Log entry, and the gap is visible by inspection.

Manual per-table weeklies are unworkable. Forty-three table pages times fifty-two weeks is over two thousand attachments per year, almost all zero-diff. A per-domain weekly bundle is more tolerable but loses the per-table locality that justifies the model in the first place. The honest move: park weeklies until an automated job exists that can diff current base state against last-known snapshot state and write a snapshot only when there is a delta. At that point, weekly cadence becomes an automation concern, not a manual procedure, and revives without re-entering the operator's loop.

This is a documented departure from the parent Schema Change Process and is called out explicitly on the Tables by Domain page so it is not silently lost.

Notion structure that supports the per-table model

Three new pages, all Platform-shaped reference docs that other domains will read but Platform owns:

The Tables by Domain page lives as a child of the Schema Change Process. It is the canonical assignment of each table in app1K2d9GZVsE7vWh to its owning domain. Platform 10, Sales 1 (orphan, no Notion home yet), Delivery 12, Revenue 20. Total 43. The page also documents the per-table snapshot model, the cross-domain rule, the weekly-skip rationale, and the ADR-0003 alignment gap. New tables get added here as part of the changeset that creates them. Reassignments require their own changeset.

A Schema Snapshots page lives as a direct child of the Platform domain page, and equivalents under Delivery and Revenue. These are the chronological changeset registries for each domain. They list every changeset that touched any table in the domain and link to the per-table attachments on the affected table pages. They do not host any JSON attachments themselves; the attachments live on the table pages.

Each table's schema page acquires a ## Schema Snapshots section near the bottom, structured as a row-per-(changeset, phase) table. A row references the JSON attachment by file name; the JSON file itself is dragged onto the same page through the Notion UI, so it lives next to the row that documents it. Attachment naming convention: <table-slug>-<YYYY-MM-DD>-<pre|post>-<changeset>.json.

Cross-domain changeset rule

A changeset authored by one domain may modify tables owned by another. Example from this session: CL-REV-0001 (Revenue-authored) adds GAAP recognition fields to the Lessons table (Delivery-owned). The rule:

The changeset is logged on the authoring domain's Schema Snapshots index, not duplicated on the affected domain's index. The per-table snapshot lives on the affected table's schema page, which is the cross-domain audit trail for that specific table. Affected-domain readers find cross-domain modifications by reading their own table pages, not by reading the other domain's index. Authoring-domain readers find their own changeset's footprint via their own index.

This avoids double-bookkeeping and gives each table a single chronological history regardless of which domain authored each change.

What this displaces

The old Tier 2 mechanics (base-wide JSON to Drive or GitHub) are not removed from the Schema Change Process page; they are now superseded by the per-table-on-changeset variant for any base where a per-table snapshots model is in use. Right now that's app1K2d9GZVsE7vWh. If new bases come online for Sales or Growth or anyone else, the same model should apply to them, with their own Tables by Domain entry (or a new manifest if cross-base) and their own per-domain Schema Snapshots index pages.

The Schema Change Process page itself has not been amended to formalize this — see the asks below.

Non-Revenue items surfaced this session

These are not parts of CL-REV-0001 itself but became visible during the working session and need Platform owners.

ADR-0003 alignment is incomplete in the legacy schema

Inspecting the Clients, Client Profiles, Students, and Student Profiles tables against ADR-0003 surfaced that the legacy Airtable schema does not implement the Person / Guardian / Participant split the ADR describes. Identity is partially in the Clients table (for the payer) and partially in the Students table (for the child). There is no proper Guardian record — guardian-of-child relationships are encoded as a Client link from Students to Clients. Client Profiles is a per-tenant junction with cross-domain rollups that mix tenancy with references into Revenue and Delivery.

Today's manifest assigns these tables to whichever domain best matches their predominant content (Clients → Platform, Client Profiles → Platform, Students → Platform, Student Profiles → Delivery). That assignment is pragmatic and reflects current state. It is not the final architecture.

A future Platform-coordinated changeset (likely CL-PLT-####) should align these tables to ADR-0003: extract canonical identity into a clean Platform record with per_ IDs, normalize First Name + DOB + phone + email + guardian links, build a proper Guardian record, retire or reshape Client Profiles into pure tenancy, and ensure operational state lives entirely on Student Profiles under Delivery. This is a significant migration with downstream effects on every Revenue and Delivery rollup that currently references the legacy tables.

Change Log section is missing from existing schema pages

Tier 1 of the Schema Change Process mandates a ## Change Log section at the bottom of every schema page. None of the existing schema pages have one — the process spec was written after the schema pages existed, and the discipline has not been retroactively propagated.

CL-REV-0001 will add ## Change Log sections to Order Items and Lessons schema pages as part of its application work, because those are the two pages it modifies. The other forty-one schema pages remain non-compliant.

A Platform-owned process changeset should backfill the section across all schema pages in one pass. The first entry in each backfilled log should explicitly note that the section was added retroactively as part of the backfill changeset and that no per-table change history exists prior to this date. That gives every page a consistent starting point and prevents future log entries from looking suspicious because the page's first entry is months newer than the page itself.

Sales has one orphan table with no Notion home

Client Conversion Summaries is a derived rollup describing per-Client conversion behavior. It is the kind of artifact Sales should own, but Sales has no Notion home today. The manifest assigns the table to Sales as the intended owner; the table sits as a manifest-orphan until a Sales domain page exists.

When Sales gets a Notion home, the next steps are mechanical: create a Sales / Schema Snapshots index page as a direct child of the Sales domain page, mirror the structure used by Platform / Delivery / Revenue, and add the Client Conversion Summaries schema page under Sales. None of this requires a changeset; it requires a Sales home to exist.

This is also a soft prompt to think about whether Sales (and Growth) need their own Airtable bases or whether they will live as additional tables in the existing one. If they live in a different base, the Tables by Domain manifest needs to either generalize across bases or be base-scoped.

Schema Change Process needs an amendment

The procedure documented in this memo (per-table snapshots, no weeklies, the manifest, the per-domain index pages) is in effect but is not yet reflected in the Schema Change Process page itself. The page still describes Tier 2 as base-wide dumps to a Drive folder or GitHub repo with weekly cadence.

A Platform-owned amendment should fold the new model into the page proper, alongside the existing description, framed as "the per-table-on-changeset variant of Tier 2 for bases where per-table snapshots are in use." The weekly-cadence section should call out the manual-skip departure with a pointer to the Tables by Domain snapshot-model section that documents it.

What Platform should action vs. acknowledge

Three asks that need a Platform-owned changeset, in order of urgency:

The Schema Change Process amendment is the most urgent because the page is currently misleading for any future reader who follows it literally. Folding the per-table model in keeps the canonical process doc honest. This is a few hours of editing work, not a deep design decision.

The Change Log backfill is medium urgency. The forty-one non-compliant pages have not caused observable problems, but the process spec is not enforced as long as those pages remain non-compliant. A single Platform-owned changeset (CL-PLT-####) that adds the section to every page in one pass closes the gap. The backfill itself is mechanical; the policy work is deciding what the first entry says.

The ADR-0003 alignment changeset is the largest and lowest urgency. It is a real migration with rollup-and-link impact across Revenue and Delivery. It does not block the GAAP work or any other in-flight Revenue changeset. It is flagged here so that whoever owns the Platform roadmap can sequence it deliberately rather than discovering it later as a surprise blocker.

One ask that needs coordination but not a Platform changeset:

The Sales home and the Sales Schema Snapshots page need to exist before the Client Conversion Summaries orphan can be properly homed. This is a Platform-coordinated decision because Platform owns the domain-page convention and the Schema Snapshots structure that Sales would inherit.

Two informational items, no action requested:

The Tables by Domain page is now part of Platform's reference doc set. It lives under Schema Change Process as a child page and should be treated as Platform-maintained.

The cross-domain changeset rule is in effect for CL-REV-0001 and any future changeset that crosses domain boundaries. The rule itself does not need Platform sign-off — it falls out of the per-table model — but Platform should be aware that the Delivery Schema Snapshots index will sometimes show no changeset rows even when Delivery's own table pages have snapshot history, because the changeset author was a different domain.

References

• Schema Change Process — parent process, currently pre-amendment
• Tables by Domain — manifest and snapshot model
• Platform / Schema Snapshots — Platform's own changeset registry, currently empty
• Delivery / Schema Snapshots
• Revenue / Schema Snapshots — has the first row populated for CL-REV-0001
• Revenue Operational Guardrails — Revenue addendum to the Schema Change Process; pairs each Revenue snapshot with a 4-number ledger reconciliation
• ADR-0001 (tenant ID shape), ADR-0002 (person ID shape), ADR-0003 (person canonical entity) — the load-bearing identity decisions referenced in this memo