Sales Navigator -- Neon + CF D1 Skill
Architecture (BAR-100 Shift)
The data layer follows a two-tier model:
| Tier |
Technology |
Role |
| Working |
CF D1 / CF KV |
Active queries, runtime state, application traffic |
| Vault |
Neon Serverless PostgreSQL |
Archival storage, migrations, canonical schema authority |
CF Workers serve as the compute layer. The Figma UI design layer connects to CF Workers,
which read/write CF D1 for working data and sync to Neon vault for long-term persistence.
What This Repo Uses
| Component |
Value |
| Hub ID |
HUB-SALES-NAV-20260130 |
| Hub Name |
sales-navigator |
| Working Database |
CF D1 (Cloudflare Workers runtime) |
| Vault Database |
Neon Serverless PostgreSQL |
| Working KV |
CF KV (session state, caches) |
| Schema |
sales (canonical), sn_* prefix (deprecated) |
| Compute Layer |
CF Workers |
| Design Layer |
Figma UI |
| Secrets Provider |
Doppler (doppler run -- npm run dev) |
| Column Registry |
column_registry.yml (canonical schema spine) |
| Canonical Migration |
sales/migrations/001_sales_schema.sql (targets Neon vault, per ADR-005) |
| Deprecated Migration |
src/data/migrations/001_create_sales_navigator_schema.sql (sn_* prefix, DO NOT execute) |
Connection Configuration
All secrets are injected via Doppler. No .env files with real values are permitted.
| Variable |
Purpose |
Injected By |
NEON_DATABASE_URL |
Neon vault connection string (migrations, archive sync) |
Doppler |
CF_D1_DATABASE_ID |
CF D1 working database identifier |
Doppler |
CF_ACCOUNT_ID |
Cloudflare account identifier |
Doppler |
CF_API_TOKEN |
Cloudflare API token for Workers/D1/KV |
Doppler |
COMPOSIO_API_KEY |
External API calls via Composio MCP |
Doppler |
Neon vault connection pattern (migrations and archive only):
# Pooled (archive reads, sync operations)
postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/dbname?sslmode=require
# Direct (migrations, admin, pg_dump)
postgresql://user:pass@ep-xxx.region.aws.neon.tech/dbname?sslmode=require
Critical: Neon is vault/archive ONLY. All application-level queries go through CF D1.
Use the Neon pooled endpoint for archive sync operations. Use the direct endpoint only for
migrations and pg_dump. See master skill IMO-Creator/skills/neon/SKILL.md for full
connection pooling rules and PgBouncer transaction-mode constraints.
Schema / Data Model
The canonical schema is defined in column_registry.yml. All generated TypeScript types and
Zod schemas are projections of this file and must never be hand-edited.
Spine Table
| Table |
Purpose |
sales.sales_state |
Phase router -- authoritative identity, gates sub-hub access |
Columns: sales_id (UUID PK, universal join key), legal_name (TEXT), domicile_state (TEXT), current_phase (TEXT: factfinder/insurance/systems/quotes), status (TEXT), source (TEXT), version (INT), created_at, updated_at
Sub-Hub Tables (4 meetings)
| Sub-Hub |
Canonical Table |
Error Table |
Key Columns |
| Meeting 1: FactFinder |
sales.sales_factfinder |
sales.sales_factfinder_errors |
employer_name, employee_count, renewal_month, prior_broker |
| Meeting 2: Insurance |
sales.sales_insurance |
sales.sales_insurance_errors |
funding_model, strategy_selected |
| Meeting 3: Systems |
sales.sales_systems |
sales.sales_systems_errors |
payroll_system, admin_model, compliance_owner |
| Meeting 4: Quotes |
sales.sales_quotes |
sales.sales_quotes_errors |
quote_version, total_cost (USD_CENTS), approved_flag |
All sub-hub tables join to spine via sales_id (TEXT). Each sub-hub has exactly 1 CANONICAL
and 1 ERROR table per OWN-10a/OWN-10b.
For the full column-level schema reference, see references/schema.md.
Operational Patterns
Phase Progression
The sales.sales_state.current_phase column gates which sub-hub is active:
factfinder -> insurance -> systems -> quotes -> [PROMOTE_TO_CLIENT]
Query Pattern (Working Layer)
Application queries go through CF Workers reading/writing CF D1. For vault operations
(reporting, archival queries), CF Workers connect to Neon via the pooled endpoint.
Schema Changes
- Update
column_registry.yml
- Run
./scripts/codegen-generate.sh
- Generated output lands in
src/data/hub/generated/ and src/data/spokes/generated/
- Pre-commit hook enforces sync between registry and generated output
- Apply migration to Neon vault, then sync D1 schema
Error Tables
All error tables are append-only. Columns: id (BIGSERIAL in Neon vault; INTEGER AUTOINCREMENT in D1),
sales_id (nullable FK), error_code, payload (JSONB in Neon; TEXT/JSON in D1), process_id, created_at.
Known Issues
- Deprecated sn_ prefix*: The original migration (
001_create_sales_navigator_schema.sql)
used sn_prospect, sn_sales_process, sn_meeting, sn_meeting_outcome tables. These
are superseded by the sales.* schema per ADR-005. Do not execute the deprecated migration.
- D1 type mapping: CF D1 uses SQLite under the hood. BIGSERIAL maps to INTEGER AUTOINCREMENT,
JSONB maps to TEXT (with JSON validation in application layer), TIMESTAMPTZ maps to TEXT (ISO-8601).
The
column_registry.yml declares Neon vault types; D1 equivalents are derived at migration time.
Cost Profile
| Resource |
Expected Usage |
Plan Consideration |
| CF D1 |
Low -- sales process is human-paced, not high-throughput |
Free tier likely sufficient during development |
| CF KV |
Minimal -- session state, caches |
Free tier covers this |
| CF Workers |
Low compute -- API routing and D1 queries |
Free tier (100k req/day) covers dev |
| Neon Vault |
< 0.5GB for prospect/meeting archive data |
Free tier covers this |
| Neon Branches |
Dev/staging branches for safe migration testing |
Launch plan if > default branch limit |
See master skill IMO-Creator/skills/neon/references/pricing.md for full Neon pricing breakdown.
1---2name: sales-neon3description: Neon PostgreSQL vault/archive configuration, schema, and operational patterns for the Sales Navigator hub (HUB-SALES-NAV-20260130). Use this skill whenever querying, migrating, debugging, or making data-layer decisions in the sales-navigator repo. Trigger on: Neon, PostgreSQL, Postgres, database, schema, sales_state, sales_factfinder, sales_insurance, sales_systems, sales_quotes, column_registry, migration, connection pooling, NEON_DATABASE_URL, pipeline tracking, prospect data, meeting data, CF D1, CF KV, Cloudflare Workers, or any reference to the sales data layer. Also trigger when discussing CRM intake, 4-meeting process state, quote approval, or PROMOTE_TO_CLIENT events. If the question touches relational data in this repo, this skill applies even if the user does not mention Neon by name.4---56# Sales Navigator -- Neon + CF D1 Skill78## Architecture (BAR-100 Shift)910The data layer follows a two-tier model:1112| Tier | Technology | Role |13|------|-----------|------|14| **Working** | CF D1 / CF KV | Active queries, runtime state, application traffic |15| **Vault** | Neon Serverless PostgreSQL | Archival storage, migrations, canonical schema authority |1617CF Workers serve as the compute layer. The Figma UI design layer connects to CF Workers,18which read/write CF D1 for working data and sync to Neon vault for long-term persistence.1920## What This Repo Uses2122| Component | Value |23|-----------|-------|24| Hub ID | HUB-SALES-NAV-20260130 |25| Hub Name | sales-navigator |26| Working Database | CF D1 (Cloudflare Workers runtime) |27| Vault Database | Neon Serverless PostgreSQL |28| Working KV | CF KV (session state, caches) |29| Schema | `sales` (canonical), `sn_*` prefix (deprecated) |30| Compute Layer | CF Workers |31| Design Layer | Figma UI |32| Secrets Provider | Doppler (`doppler run -- npm run dev`) |33| Column Registry | `column_registry.yml` (canonical schema spine) |34| Canonical Migration | `sales/migrations/001_sales_schema.sql` (targets Neon vault, per ADR-005) |35| Deprecated Migration | `src/data/migrations/001_create_sales_navigator_schema.sql` (sn_* prefix, DO NOT execute) |3637## Connection Configuration3839All secrets are injected via Doppler. No `.env` files with real values are permitted.4041| Variable | Purpose | Injected By |42|----------|---------|-------------|43| `NEON_DATABASE_URL` | Neon vault connection string (migrations, archive sync) | Doppler |44| `CF_D1_DATABASE_ID` | CF D1 working database identifier | Doppler |45| `CF_ACCOUNT_ID` | Cloudflare account identifier | Doppler |46| `CF_API_TOKEN` | Cloudflare API token for Workers/D1/KV | Doppler |47| `COMPOSIO_API_KEY` | External API calls via Composio MCP | Doppler |4849**Neon vault connection pattern (migrations and archive only):**50```51# Pooled (archive reads, sync operations)52postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/dbname?sslmode=require5354# Direct (migrations, admin, pg_dump)55postgresql://user:pass@ep-xxx.region.aws.neon.tech/dbname?sslmode=require56```5758**Critical:** Neon is vault/archive ONLY. All application-level queries go through CF D1.59Use the Neon pooled endpoint for archive sync operations. Use the direct endpoint only for60migrations and `pg_dump`. See master skill `IMO-Creator/skills/neon/SKILL.md` for full61connection pooling rules and PgBouncer transaction-mode constraints.6263## Schema / Data Model6465The canonical schema is defined in `column_registry.yml`. All generated TypeScript types and66Zod schemas are projections of this file and must never be hand-edited.6768### Spine Table6970| Table | Purpose |71|-------|---------|72| `sales.sales_state` | Phase router -- authoritative identity, gates sub-hub access |7374Columns: `sales_id` (UUID PK, universal join key), `legal_name` (TEXT), `domicile_state` (TEXT), `current_phase` (TEXT: factfinder/insurance/systems/quotes), `status` (TEXT), `source` (TEXT), `version` (INT), `created_at`, `updated_at`7576### Sub-Hub Tables (4 meetings)7778| Sub-Hub | Canonical Table | Error Table | Key Columns |79|---------|----------------|-------------|-------------|80| Meeting 1: FactFinder | `sales.sales_factfinder` | `sales.sales_factfinder_errors` | employer_name, employee_count, renewal_month, prior_broker |81| Meeting 2: Insurance | `sales.sales_insurance` | `sales.sales_insurance_errors` | funding_model, strategy_selected |82| Meeting 3: Systems | `sales.sales_systems` | `sales.sales_systems_errors` | payroll_system, admin_model, compliance_owner |83| Meeting 4: Quotes | `sales.sales_quotes` | `sales.sales_quotes_errors` | quote_version, total_cost (USD_CENTS), approved_flag |8485All sub-hub tables join to spine via `sales_id` (TEXT). Each sub-hub has exactly 1 CANONICAL86and 1 ERROR table per OWN-10a/OWN-10b.8788For the full column-level schema reference, see `references/schema.md`.8990## Operational Patterns9192### Phase Progression93The `sales.sales_state.current_phase` column gates which sub-hub is active:94```95factfinder -> insurance -> systems -> quotes -> [PROMOTE_TO_CLIENT]96```9798### Query Pattern (Working Layer)99Application queries go through CF Workers reading/writing CF D1. For vault operations100(reporting, archival queries), CF Workers connect to Neon via the pooled endpoint.101102### Schema Changes1031. Update `column_registry.yml`1042. Run `./scripts/codegen-generate.sh`1053. Generated output lands in `src/data/hub/generated/` and `src/data/spokes/generated/`1064. Pre-commit hook enforces sync between registry and generated output1075. Apply migration to Neon vault, then sync D1 schema108109### Error Tables110All error tables are append-only. Columns: `id` (BIGSERIAL in Neon vault; INTEGER AUTOINCREMENT in D1),111`sales_id` (nullable FK), `error_code`, `payload` (JSONB in Neon; TEXT/JSON in D1), `process_id`, `created_at`.112113## Known Issues114115- **Deprecated sn_* prefix**: The original migration (`001_create_sales_navigator_schema.sql`)116 used `sn_prospect`, `sn_sales_process`, `sn_meeting`, `sn_meeting_outcome` tables. These117 are superseded by the `sales.*` schema per ADR-005. Do not execute the deprecated migration.118- **D1 type mapping**: CF D1 uses SQLite under the hood. BIGSERIAL maps to INTEGER AUTOINCREMENT,119 JSONB maps to TEXT (with JSON validation in application layer), TIMESTAMPTZ maps to TEXT (ISO-8601).120 The `column_registry.yml` declares Neon vault types; D1 equivalents are derived at migration time.121122## Cost Profile123124| Resource | Expected Usage | Plan Consideration |125|----------|---------------|-------------------|126| CF D1 | Low -- sales process is human-paced, not high-throughput | Free tier likely sufficient during development |127| CF KV | Minimal -- session state, caches | Free tier covers this |128| CF Workers | Low compute -- API routing and D1 queries | Free tier (100k req/day) covers dev |129| Neon Vault | < 0.5GB for prospect/meeting archive data | Free tier covers this |130| Neon Branches | Dev/staging branches for safe migration testing | Launch plan if > default branch limit |131132See master skill `IMO-Creator/skills/neon/references/pricing.md` for full Neon pricing breakdown.
FDU-INS