# 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