437 lines
10 KiB
Markdown
437 lines
10 KiB
Markdown
# 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.
|