Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack/09 - Database Schema and Root API Spec_ Founder CRM Canonical Domains.md

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.