Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack/03 - SRS_ Founder CRM and Platform Planning.md

Software Requirements Specification (SRS)_ Founder CRM and Platform Planning

Date: 2026-04-18
Status: Draft
Owner: Sagnik
Reviewers: Sayan, Sourik
Scope: Planning specification for CRM module definition, canonical domains, import pipeline, Oracle adjacency, and operator truth
Purpose: Define the technical requirements, route targets, data boundaries, and acceptance criteria for the founder-side convergence work.
Decision Boundary: This SRS specifies the target architecture for approval and later implementation. It does not itself execute migrations or route changes.

1. Purpose

This SRS specifies the target technical shape of the founder-owned CRM and platform planning layer that will anchor the next implementation phase of Project Velocity.

2. System Context

This work sits across several existing subsystems:

• backend root runtime in backend/main.py
• current CRM routes in backend/api/routes_crm.py
• current Oracle routes in backend/api/routes_oracle.py
• Oracle router v1 services under backend/oracle/
• Oracle frontend canvas in app/src/app/oracle/page.tsx
• current module shell in app/src/App.tsx
• current schemas in backend/db/schema.sql and schema_addendum.sql

The system must integrate with:

• existing auth model
• existing Oracle runtime
• existing perception/Sentinel data
• existing Catalyst and inventory concepts
• current infra deployment topology

3. Assumptions and Constraints

• CRM must be planned as a top-level module.
• Oracle remains adjacent, not authoritative over operational CRM.
• live infra truth must be reflected exactly.
• old tables remain inputs to migration planning.
• import must be CSV-first and mapping-driven.

4. Functional Architecture

Planned runtime domains:

• crm domain
• intel domain
• inventory domain
• oracle domain
• core identity/access domain
• workflow governance domain

Planned UI surfaces:

• top-level CRM module
• CRM subpages for contacts, accounts, opportunities, tasks, imports, client 360, reports
• Oracle subtabs for CRM intelligence, import review, client 360 adjacency

5. Functional Requirements

SRS-FR-01

• description: define a canonical CRM module in the Velocity shell
• producer: planning docs
• consumer: future frontend and backend implementation
• acceptance: module spec and PRD align on CRM as top-level

SRS-FR-02

• description: define canonical namespaced domains for client data
• producer: database and schema planning docs
• consumer: backend schema and route work
• acceptance: all required domains and target tables are enumerated

SRS-FR-03

• description: define a raw-to-canonical import architecture
• producer: adapter and schema docs
• consumer: future import services and review UX
• acceptance: source file, mapping manifest, canonical projections, and approval flow are all defined

SRS-FR-04

• description: define route families for CRM, Oracle, inventory, admin, and runtime ownership
• producer: root API spec
• consumer: backend implementation
• acceptance: target route families are listed with ownership and current-state markers

SRS-FR-05

• description: define migration posture from current tables to canonical domains
• producer: DB spec and reconciliation matrix
• consumer: future migration work
• acceptance: old tables are mapped to canonical domains and marked as legacy feeders

6. Interface Requirements

Target public interface families:

• /api/crm/contacts
• /api/crm/accounts
• /api/crm/opportunities
• /api/crm/tasks
• /api/crm/interactions
• /api/crm/imports
• /api/crm/client-360/{client_id}
• /api/crm/qd/{client_id}
• /api/oracle/templates
• /api/oracle/canvas/*
• /api/inventory/*
• /api/admin/*
• /api/runtime/*
• /api/colony/*

Internal planning interfaces to define:

• raw import batch contract
• mapping manifest contract
• enrichment suggestion contract
• Oracle writeback proposal contract
• approval event contract

7. Data Model

Canonical planned domains:

• crm_*
• intel_*
• inventory_*
• oracle_*
• core_*
• workflow_*

Core lifecycle objects:

• raw evidence
• normalized entity
• inferred enrichment
• proposed writeback
• approved writeback
• audit event

8. Non-Functional Requirements

8.1 Reliability

• documents must be grounded in current repo truth
• route ownership must be explicit
• operator infra truth must not rely on memory

8.2 Scalability

• canonical model must support growth from simple CRM to AI-native graph without schema collapse

8.3 Security

• approval boundaries and access roles must be documented
• high-risk writes must remain reviewable

8.4 Privacy

• communications, transcripts, and recordings must be treated as governed evidence

8.5 Observability

• planning docs must specify audit and provenance expectations for future implementation

8.6 Fault Tolerance

• unresolved imports and ambiguous joins must degrade to review tasks, not silent loss

8.7 Licensing

• external references may inform import assumptions, but architecture remains Velocity-owned

9. Evaluation and Testing Strategy

Planning validation requires:

• repo-to-doc reconciliation review
• interface consistency review across PRD, SRS, blueprint, and DB spec
• owner review across founder, Sayan, and Sourik domains
• synthetic-data brief completeness check

10. Migration and Fork Plan

Reuse:

• existing backend root
• current auth and Oracle runtime

Fork/rework:

• CRM surface model
• canonical schema
• import pipeline
• inventory persistence model

Migration planning must map:

• leads and leads_intelligence
• chat_logs and omnichannel_logs
• perception/session tables
• asset and consent tables

11. Open Questions

• how much of the current frontend CRM state store should survive
• whether crm_people and crm_leads should remain distinct over time
• how identity resolution should be staged in early imports

12. Acceptance Criteria

• all target route families and domains are named
• legacy feeders are mapped
• top-level CRM positioning is consistent across documents
• infra/operator truth is consistent with current deployment docs
• synthetic-data brief is implementable without further architectural choices