Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack/05 - Implementation Blueprint_ Founder CRM and Platform Planning.md

Implementation Blueprint_ Founder CRM and Platform Planning

Date: 2026-04-18
Status: Draft
Owner: Sagnik
Reviewers: Sayan, Sourik
Scope: Repository mapping and target runtime shape for the future CRM/client-graph convergence work
Purpose: Convert the founder-side planning decisions into a repo-aware implementation skeleton tied to the current codebase.
Decision Boundary: This is a planning blueprint. File and route creation are future work.

1. Purpose

This blueprint maps the current repo truth to the future founder-owned CRM and platform work so implementation can proceed later without re-discovering the architecture.

2. Current State Mapping

2.1 Root Backend Truth

Current backend truth already includes:

• auth endpoints
• CRM routes in backend/api/routes_crm.py
• Oracle routes in backend/api/routes_oracle.py
• Oracle router v1 services under backend/oracle/
• Sentinel, CCTV, scenes, videos, vault, catalyst routes
• websocket paths for Catalyst and CRM

2.2 Domain Truth

Current domain reality:

• Oracle is real and mounted
• CRM exists, but its schema is still lightweight and overlapping with older tables
• inventory persistence is not canonical yet
• perception/evidence tables exist, but are not yet unified under one client graph

2.3 Frontend Truth

Current top-level modules in app/src/App.tsx:

• dashboard
• oracle
• sentinel
• inventory
• catalyst
• settings

Current gap:

• there is no top-level CRM module yet

3. Target Runtime Shape

Root authority

• backend root remains the route authority and identity boundary

Internal service authority

• CRM services own canonical client graph projections
• Oracle services own analytical canvas and writeback proposal generation
• import intelligence services own raw-to-canonical transformation assistance

Governance authority

• approval and audit sit in a shared workflow/governance domain

This split is correct because operational ownership, analysis, and approval are related but not identical responsibilities.

4. File-by-File Repository Blueprint

Planned future additions or reorganizations:

• app/src/components/modules/CRM.tsx
• app/src/components/crm/*
• app/src/lib/crm/*
• backend/api/routes_crm_v2.py or equivalent future canonical route surface
• backend/services/crm/*
• backend/services/imports/*
• backend/services/client_graph/*
• future schema or migration units under backend/db/

Planning-only artifacts added in this sprint live in:

• Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack
• Project_Velocity/.Agent Context/Project Velocity Monolithic Truth.md

5. Runtime Flow

Planned runtime path:

1. user enters CRM
2. CRM fetches canonical client graph slices
3. Oracle reads from the same canonical graph when analytical context is needed
4. imports land raw source data
5. AI proposes normalization
6. approved writebacks update canonical domains
7. downstream modules consume the updated client graph

6. Planned Root Files

• future CRM module shell
  • owner: Founder
  • purpose: top-level operational CRM surface
• future CRM route family
  • owner: Founder with Sourik review
  • purpose: canonical CRUD and interaction APIs
• future import route family
  • owner: Founder
  • purpose: source ingestion and mapping workflow

7. Planned Service Files

• client graph aggregation service
• import normalization service
• mapping profile service
• identity resolution service
• QD rollup service

These remain proposed and should not be implemented until the DB and route planning docs are approved.

8. Mission, Artifact, and Persistence Plan

Key planned artifacts:

• raw import batch
• mapping manifest
• canonical client entity set
• interaction bundle
• enrichment proposal
• writeback proposal
• approval event

Persistence posture:

• raw evidence retained
• structured canonical projections stored separately
• audit and provenance retained across both

9. Adapter Plan

Planned adapter rollout:

1. CRM import adapter
2. client 360 aggregation adapter
3. Oracle insight adapter over canonical CRM
4. inventory-to-client-interest adapter

10. Governance Plan

Policy enforcement should live in the future shared workflow/governance layer and control:

• approval requirements
• confidence thresholds
• merge safety
• sensitive writebacks

11. Testing and Operationalization Plan

Future implementation should require:

• schema contract tests
• import replay tests
• CRM page integration tests
• Oracle-to-CRM writeback tests
• synthetic dataset verification

12. Build Order

1. canonical schema and route planning approval
2. CRM shell and route family
3. import layer
4. client 360 aggregate
5. Oracle CRM-adjacent tabs
6. inventory and QD enrichments

13. Non-Negotiables

• CRM is top-level
• Oracle is adjacent, not primary CRM shell
• old tables are migration feeders, not final truth
• Linux origin, ingress, and Comfy routing must remain aligned with live infra truth
• GPU model work remains on NVMe-backed Comfy infrastructure only

14. Bottom Line

The blueprint shows that the missing work is not backend existence. The missing work is canonical structure and clean attachment points. Once those are approved, implementation can proceed with much less architectural drift.