Airtable Integration Map

Status: active working map Canonical scope: Airtable touchpoints across marketing, portals, APIs, automations, and webhook handoffs Last updated: 2026-03-09

1. Runtime contract in code

Environment variables the app currently expects

Bases and tables currently wired in code

Tables explicitly missing in the current Airtable layer

2. Current Airtable touchpoint matrix

3. Current project-side Airtable dependencies

Core Airtable module

Primary file:

• airtable.ts

What it currently owns:

• base selection
• table selection
• field mappers for Client, Doula, Contract, Product
• generic CRUD wrappers
• filter builders
• duplicate detection for parent intake

What it does not fully own yet:

• explicit Airtable availability/time-off tables
• live PandaDoc credentials, template activation, and production webhook registration

Specialized Airtable mapping layer

Parent intake mapper:

• parent-intake.ts

This is now the canonical public intake field contract. It must match the live Airtable field names exactly.

Routes that rely directly on Airtable availability

4. What must exist inside Airtable for the next implementation wave

Launch-critical cutover set

Airtable automations that the app expects or will expect

5. Current blockers and drift

6. Active Airtable automations and live-side-effect risk

Parent Database

Confirmed active automations:

• Parent Sign Up Created
• Postpartum Check-In!
• First Birthday Email
• Final Payment Reminder
• Email response to referral form
• Parent - Hired to Contract
• New Contracts to Bookkeeping Spreadsheet
• Post to Availability
• Closed Contracts

Key confirmed trigger:

• Parent Sign Up Created
  • trigger: record created in Parent Intake Forms
  • actions: sends email
  • branch logic: Kaiser Benefit?

Risk implication:

• a real insert into Parent Intake Forms is not a harmless test write
• it can trigger Gmail, Slack, Google Sheets, and downstream contract/availability workflows

Doula Database

Confirmed active automations:

• Directory Doula Confirmation Email With Payment Link
• [TBC Doula Database] Send Webhook when Record is Updated
• [Doula Directory] Send Webhook when Record is Created
• [TBC Doula Database] Send Webhook when Record is Created copy

Confirmed inactive automations:

• New Doula Sign Up Email Confirmation With Doula Profile Form
• Update Record via Form V2
• [Join The Team Form Submission] Send Webhook when Record is Created ...
• Yurii

Risk implication:

• writes to TBC Doula Database and Provider Directory can trigger webhook side effects
• the public doula application destination table still needs to be chosen explicitly before any live submit test

Family Favorites

Confirmed active automations:

• Send Webhook [Record Updated]
• Send Webhook [Record Created]

Risk implication:

• product/content table edits can fire webhooks immediately

Marketing

No automation screenshots were provided for Marketing.

Current assumption:

• treat Marketing as potentially side-effectful until explicitly verified otherwise

Payments / TBC Admin Database

• user confirmed the old Payments base was deleted
• any screenshots of that base should be treated as stale
• TBC Admin Database now exists with Admin Payments
• no active automation screenshots were provided yet for TBC Admin Database

7. Safe testing rules for Airtable cutover work

These are mandatory until the production automations are fully cataloged.

1. Do not run live create/update tests against Parent Intake Forms while create-trigger automations are enabled unless the user explicitly approves the side effects.
2. Do not assume a "test record" is safe. A single insert can trigger Gmail, Slack, Google Sheets, and contract/availability workflows.
3. Do not run any delete operations against Airtable production bases.
4. Prefer one of these testing modes, in order:
   • sandbox/test base copy
   • temporary automation disablement during a controlled test
   • production write with explicit operator approval and known side effects
5. Any production write test must use:
   • a clearly labeled test identity
   • a unique email
   • a single insert-only action
   • no cleanup delete unless explicitly approved

8. Canonical table-role decisions

These need explicit decisions before more write paths are wired.

Doula application destination

Current ambiguity:

• TBC Doula Database has a form called Doula Profile Form
• Provider Directory has a form view called Doula Intake Form

Decision required:

• which table is the canonical destination for public doula applications?

Recommended default:

• TBC Doula Database for internal/application records
• Provider Directory for public/provider listing records only
• this is now the live app behavior for approval, directory publication, and mentorship

Payments domain

Canonical model:

• old Payments base is deleted
• TBC Admin Database exists with Admin Payments
• Parent Database contains Parents Payments
• Active Contracts is the canonical contract-economics record once PandaDoc metadata is ingested
• PandaDoc send/status/webhook scaffolding now exists in the app code, but live activation still depends on production credentials and webhook registration
• Parents Payments is the canonical external money-in ledger
• Admin Payments is the canonical internal contract-level finance and payout ledger

Relationship model:

• one Active Contracts record exists per signed PandaDoc contract
• one contract can have many Parents Payments rows
• one contract should have one Admin Payments row

Field ownership:

• Active Contracts
  • total contract value
  • deposit due
  • balance due
  • referral fee percent
  • referral fee amount
  • doula payout obligation
  • Kaiser billing owner / handling
  • PandaDoc reference
• Parents Payments
  • parent/client
  • contract
  • payment stage (deposit, final, other)
  • gross amount received
  • payment method / external reference
  • paid date
  • receipt status
• Admin Payments
  • contract
  • total received to date
  • remaining due
  • referral fee captured
  • doula payout due
  • payout status / paid date / payout method
  • bookkeeping notes

Operational rule:

• client-facing pages must not use Admin Payments as the source of truth for money received
• admin payout and referral-fee state must not derive only from Parents Payments without contract context

9. Connection map

flowchart LR
  subgraph Marketing["Marketing Site"]
    PI["/parent-intake-form"]
    DS["/doula-sign-up"]
    DL["/doulas"]
  end

  subgraph Portals["Client / Doula / Admin Portals"]
    CI["Client portal"]
    DP["Doula portal"]
    AP["Admin portal"]
  end

  subgraph App["Next.js API + mapping layer"]
    APIClients["/api/clients"]
    APIDoulas["/api/doulas"]
    APIContracts["/api/contracts"]
    APIPayments["/api/payments"]
    APIAppointments["/api/appointments"]
    APIStats["/api/admin/stats"]
    APIWebhookPayment["/api/webhooks/payment"]
    APIWebhookZapier["/api/webhooks/zapier"]
    AirtableLib["lib/airtable.ts"]
    ParentMapper["lib/parent-intake.ts"]
  end

  subgraph Airtable["Airtable"]
    ParentsBase["Parent Database"]
    DoulasBase["Doula Database"]
    ProductsBase["Family Favorites base"]
    MarketingBase["Marketing base"]
    AdminBase["TBC Admin Database"]
    MissingOps["Missing ops tables\n(Invoices / Availability / Time Off)"]
  end

  subgraph Automation["Automations and external systems"]
    AirtableAutos["Airtable automations"]
    Zapier["Zapier"]
    Plaid["Plaid"]
    Clerk["Clerk"]
    Google["Google Calendar / Meet"]
  end

  PI --> APIClients
  DS --> APIDoulas
  DL --> APIDoulas
  CI --> APIClients
  DP --> APIDoulas
  AP --> APIStats
  AP --> APIContracts
  AP --> APIPayments
  CI --> APIAppointments
  DP --> APIAppointments

  APIClients --> ParentMapper
  ParentMapper --> AirtableLib
  APIDoulas --> AirtableLib
  APIContracts --> AirtableLib
  APIPayments --> AirtableLib
  APIAppointments --> AirtableLib
  APIStats --> AirtableLib

  AirtableLib --> ParentsBase
  AirtableLib --> DoulasBase
  AirtableLib --> ProductsBase
  AirtableLib --> MarketingBase
  AirtableLib --> AdminBase
  AirtableLib -. required next .-> MissingOps

  ParentsBase --> AirtableAutos
  DoulasBase --> AirtableAutos
  AirtableAutos --> Clerk
  AirtableAutos --> Google

  Plaid --> APIWebhookPayment
  Zapier --> APIWebhookPayment
  Zapier --> APIWebhookZapier
  APIWebhookPayment --> APIPayments
  APIWebhookPayment --> APIContracts
  APIWebhookZapier --> AirtableLib

10. Immediate execution order for the Airtable call

11. Hard truths

• The current codebase is not built around one single Airtable base. It is already a multi-base model.
• Parent intake is the closest public lead flow to production. Doula application is next. Matching, interviews, and payment ledgers are now Airtable-backed.
• Payments are no longer structurally ambiguous. The remaining work is invoice approval workflow polish plus live PandaDoc activation, not ledger ownership, invoice persistence, or receipt dedupe.
• A live Airtable write is not equivalent to a harmless database insert. In this workspace, it can trigger real outbound automations immediately.
• If the call tries to redesign the entire Airtable architecture from scratch, you will lose time. The highest-return move is targeted cutover of the next four missing workflows.