# Database Schema and Root API Spec_ Founder CRM Canonical Domains

**Date:** 2026-04-18  
**Status:** Draft  
**Owner:** Sagnik  
**Reviewers:** Sayan, Sourik  
**Scope:** Canonical target tables, route families, repository expectations, and migration posture for founder-owned CRM and client graph work  
**Purpose:** Define the database schema, root repository behavior, and API surface required for the future CRM-centered Project Velocity architecture.  
**Decision Boundary:** This spec defines the target persistence and route truth for approval. It does not itself execute schema or API changes.

## 1. Purpose

This spec exists because the current repo contains multiple overlapping data surfaces that are real but not yet canonical. Future implementation needs one agreed target.

## 2. Design Principles

- canonical domains are namespaced by responsibility
- raw evidence and normalized projections both exist
- current tables are migration feeders, not ignored
- root API families should reflect ownership, not accidental code layout
- read models such as client 360 are derived, not primary truth

## 3. Schema Files

Future implementation should likely introduce:

- canonical CRM schema or migration unit
- canonical interaction/evidence schema or migration unit
- canonical inventory schema or migration unit
- workflow/governance schema or migration unit
- read-model or materialized-view support where needed

## 4. Required Tables

### CRM core domain

- `crm_people`
- `crm_accounts`
- `crm_households`
- `crm_relationships`
- `crm_leads`
- `crm_opportunities`
- `crm_property_interests`
- `crm_stage_history`

### Interaction and evidence graph domain

- `intel_interactions`
- `intel_messages`
- `intel_calls`
- `intel_call_recordings`
- `intel_transcripts`
- `intel_emails`
- `intel_whatsapp_threads`
- `intel_visits`
- `intel_reminders`
- `intel_qd_scores`
- `intel_qd_timeseries`
- `intel_vehicle_events`
- `intel_perception_events`
- `intel_cctv_links`
- `intel_blob_store_index`

### Inventory domain

- `inventory_projects`
- `inventory_units`
- `inventory_pricing_history`
- `inventory_availability`
- `inventory_media`
- `inventory_location_index`
- `inventory_import_jobs`

### Oracle component/template domain

- `oracle_component_families`
- `oracle_component_chapters`
- `oracle_component_templates`
- `oracle_component_examples`
- `oracle_component_tags`
- `oracle_component_lineage`

### Identity and access domain

- `core_users`
- `core_roles`
- `core_permissions`
- `core_role_assignments`
- `core_sessions`
- `core_audit_events`

### AI workflow and governance domain

- `workflow_actions`
- `workflow_branches`
- `workflow_approvals`
- `workflow_writebacks`
- `workflow_agent_runs`
- `workflow_policy_decisions`

## 5. Detailed Table Plan

### `crm_people`

- purpose: canonical person-level contact identity
- recommended columns:
  - `person_id`
  - `full_name`
  - `primary_email`
  - `primary_phone`
  - `linkedin_url`
  - `persona_labels`
  - `source_confidence`
  - `created_at`
  - `updated_at`
- indexes:
  - email
  - phone
  - normalized name

### `crm_accounts`

- purpose: company, developer, brokerage, or client organization record
- recommended columns:
  - `account_id`
  - `account_name`
  - `parent_account_id`
  - `account_type`
  - `industry`
  - `location_ref`
  - `metadata_json`

### `crm_leads`

- purpose: funnel-stage commercial qualification layer
- note: distinct from `crm_people`; one person may have one or more lead/opportunity contexts
- recommended columns:
  - `lead_id`
  - `person_id`
  - `account_id`
  - `source_system`
  - `status`
  - `stage`
  - `budget_band`
  - `urgency`
  - `assigned_user_id`
  - `created_at`

### `crm_opportunities`

- purpose: deal pipeline objects
- recommended columns:
  - `opportunity_id`
  - `lead_id`
  - `project_id`
  - `unit_id`
  - `stage`
  - `value`
  - `probability`
  - `expected_close_date`
  - `next_action`

### `intel_interactions`

- purpose: umbrella interaction event record
- recommended columns:
  - `interaction_id`
  - `person_id`
  - `channel`
  - `interaction_type`
  - `happened_at`
  - `summary`
  - `source_ref`

### `intel_messages`

- purpose: text-level message records
- recommended columns:
  - `message_id`
  - `interaction_id`
  - `sender_role`
  - `message_text`
  - `delivered_at`
  - `metadata_json`

### `intel_calls`

- purpose: call-level records
- recommended columns:
  - `call_id`
  - `interaction_id`
  - `call_direction`
  - `duration_seconds`
  - `recording_ref`
  - `transcript_ref`

### `intel_transcripts`

- purpose: transcript and speaker segmentation storage
- recommended columns:
  - `transcript_id`
  - `call_id`
  - `language`
  - `full_text`
  - `speaker_segments_json`
  - `confidence`

### `intel_visits`

- purpose: site visits and meeting records
- recommended columns:
  - `visit_id`
  - `person_id`
  - `project_id`
  - `unit_id`
  - `visited_at`
  - `visit_notes`
  - `host_user_id`

### `intel_qd_scores`

- purpose: latest meaningful QD summary by client or interaction context
- recommended columns:
  - `qd_id`
  - `person_id`
  - `score_type`
  - `current_value`
  - `computed_at`
  - `evidence_refs_json`

### `intel_qd_timeseries`

- purpose: time-series view of QD propagation and shifts
- recommended columns:
  - `timeseries_id`
  - `person_id`
  - `signal_source`
  - `timestamp`
  - `value`
  - `evidence_ref`

### `inventory_projects`

- purpose: project-level inventory master
- recommended columns:
  - `project_id`
  - `project_name`
  - `developer_name`
  - `city`
  - `micro_market`
  - `location_json`

### `inventory_units`

- purpose: unit-level availability and attributes
- recommended columns:
  - `unit_id`
  - `project_id`
  - `unit_label`
  - `configuration`
  - `area_sqft`
  - `price_current`
  - `status`
  - `facing`
  - `floor`

### `core_users`

- purpose: canonical user identity
- note: future target wrapper over current `users_and_roles`

### `workflow_writebacks`

- purpose: track AI-suggested and approved mutations
- recommended columns:
  - `writeback_id`
  - `proposal_ref`
  - `target_domain`
  - `target_entity_ref`
  - `status`
  - `approved_by`
  - `executed_at`

## 6. Root Modules

Future root/backend layers should include:

- CRM repository module
- import gateway module
- client graph aggregation gateway
- workflow/policy bridge
- route modules grouped by route family

## 7. Root API Surface

### `/api/crm/contacts`

- method family: `GET`, `POST`, `PUT`
- purpose: browse and update person/contact records
- access control: authenticated CRM roles

### `/api/crm/accounts`

- method family: `GET`, `POST`, `PUT`
- purpose: browse and update account/company records

### `/api/crm/opportunities`

- method family: `GET`, `POST`, `PUT`
- purpose: pipeline/deal records

### `/api/crm/tasks`

- method family: `GET`, `POST`, `PUT`
- purpose: reminders, follow-ups, and assigned work

### `/api/crm/interactions`

- method family: `GET`, `POST`
- purpose: unified interaction timeline access

### `/api/crm/imports`

- method family: `POST`, `GET`
- purpose: import batch submission, review, and status

### `/api/crm/client-360/{client_id}`

- method family: `GET`
- purpose: aggregated client dossier read model

### `/api/crm/qd/{client_id}`

- method family: `GET`
- purpose: QD summary and timeline access

### `/api/oracle/templates`

- method family: `GET`, `POST`, `PUT`
- purpose: template family and example management

### `/api/oracle/canvas/*`

- method family: mixed
- purpose: Oracle canvas runtime and CRM-adjacent intelligence views

## 8. Lifecycle States

Suggested lifecycle families:

- import: `uploaded -> parsed -> mapped -> proposed -> approved -> committed -> failed`
- writeback: `draft -> review_required -> approved -> executed -> rejected`
- opportunity: stage-based commercial pipeline states

## 9. Writeback Release Flow

1. Oracle or import intelligence proposes a change
2. proposal is stored under workflow domain
3. operator approves or rejects
4. approved change writes into canonical domain
5. audit event is stored

## 10. Repository Contract

Minimum future repository methods:

- fetch contact list
- fetch account list
- fetch client 360
- list unresolved import proposals
- apply approved writeback
- list interaction timeline by client
- fetch QD history by client
- fetch property interests by client

## 11. Query Shapes

- summary query
  - client list with last activity, active opportunity count, and QD summary
- artifact query
  - full interaction or transcript artifact by ID
- replay query
  - import batch with mapping and approval history
- operator inbox query
  - unresolved proposals, reminders, and high-risk merges

## 12. Concurrency and Idempotency Rules

- import retries must not duplicate canonical rows blindly
- repeated writeback execution must be idempotent
- merges require conflict-safe guards

## 13. Security and Access Control

- authenticated access required
- role-based access over CRM and admin functions
- sensitive communication artifacts subject to least-privilege access
- high-risk writes require approval

## 14. Migration and Rollout Plan

Legacy-to-canonical mapping posture:

- `leads` and `leads_intelligence` feed CRM core
- `chat_logs` and `omnichannel_logs` feed interaction graph
- `consent_log` feeds governance/compliance
- `velocity_vault_assets`, `cctv_events`, `perception_sessions`, and `video_scene_maps` feed evidence graph
- `users_and_roles` becomes the input to future `core_*` identity design

Rollout should occur in this order:

1. canonical schema approval
2. import layer and CRM route family
3. client 360 read model
4. Oracle/CRM writeback flow

## 15. Acceptance Criteria

- target domains and route families are complete
- old tables are explicitly mapped, not ignored
- route family ownership is explicit
- schema design is detailed enough for implementation planning

## 16. Ticket Breakdown

- canonical schema design
- import batch ingestion
- mapping review flow
- CRM contact/account/opportunity routes
- client 360 aggregation
- writeback governance
- Oracle template DB

## 17. Bottom Line

The repo does not need more unnamed tables or more accidental route growth. It needs one canonical model that the rest of Project Velocity can finally build against.