# Founder CRM and Platform Planning - First Principles and Product Understanding **Date:** 2026-04-18 **Status:** Draft **Owner:** Sagnik **Reviewers:** Sayan, Sourik **Scope:** Founder-owned CRM, client graph, import architecture, Oracle adjacency, and platform truth consolidation **Purpose:** Define the founder-side product and architecture logic from first principles before the next round of implementation begins. **Decision Boundary:** This document sets the design intent and evaluation logic. It does not itself commit the repo to code migration. ## Executive Summary Project Velocity is no longer blocked by lack of infrastructure. The current problem is lack of canonical product truth across CRM, client intelligence, imports, and platform boundaries. The system already contains: - a real backend - a real Oracle runtime - a real Sentinel/perception spine - a real Catalyst surface - a partial CRM implementation - raw inventory onboarding assets What it does not yet contain is one clean answer to the founder question: > Where do I see every client, every interaction, every property interest, every risk signal, and every next action in one operational system? The target improvement is to define that answer as a top-level CRM module backed by an AI-native canonical data model and surrounded by clear infrastructure and ownership truth. ## Assumptions and Constraints ### Assumptions - Project Velocity is being built as a high-touch sales operating system for premium real estate teams. - The target buyer expects more than a contact list; they expect an intelligent client dossier. - Oracle remains an intelligence and analytical canvas, not the sole operational home of CRM. - CSV is the correct first import substrate because it gives the widest initial system compatibility. - NemoClaw or related agent layers will enrich and steward imported data, but humans remain the approval authority for committed changes. ### Constraints - Existing repo truth cannot be ignored in favor of greenfield fantasy. - Existing handoffs to Sayan and Sourik create real ownership boundaries that this planning layer must respect. - The current database state is overlapping and inconsistent, so migration posture has to be explicit. - Infra truth must align with live deployment reality: - Linux origin on `192.168.1.2` - stable ingress - Comfy exposed through `https://comfy.desineuron.in` - GPU model/runtime work on NVMe only ## Reference Sources and Rationale ### Local Sources - `Project_Velocity/.Agent Context/Sprint 1/Sprint 1 Fact Table - 2026-04-12.md` - required because it contains the old summary that now needs reconciliation - `Project_Velocity/.Agent Context/Sprint 1/comfyui_setup_truth.md` - required because it holds the current GPU/Comfy deployment truth - `Project_Velocity/.Agent Context/Sprint 1/Desineuron Stable Ingress Handoff.md` - required because it holds ingress, public routing, and operator details - `Project_Velocity/.Agent Context/Sprint 1/CRM Modules-Abantika Recommendations.txt` - required because it expresses the target customer’s CRM expectations in direct language - `Project_Velocity/backend/main.py` - required because it shows the real mounted backend architecture - `Project_Velocity/backend/api/routes_crm.py` - required because it shows what CRM actually exists today - `Project_Velocity/backend/api/routes_oracle.py` - required because it shows how Oracle actions and writebacks currently behave - `Project_Velocity/backend/db/schema.sql` and `schema_addendum.sql` - required because they reveal the current persistence split - `Project_Velocity/app/src/App.tsx` - required because it shows the current top-level module map - `Project_Velocity/app/src/app/oracle/page.tsx` - required because it shows Oracle as a real first-class product surface ### Upstream or External Sources - Salesforce product patterns - used for operational CRM expectations, not for literal UX cloning - HubSpot and Jira CSV import patterns - used to justify CSV-first import posture ## Problem Statement The current failure mode is not that Velocity lacks capability. The failure mode is that its capability is fragmented across subsystems, incomplete schemas, and uneven UI entry points. This causes business damage in three ways: 1. demo fragility an intelligent sales system looks incomplete if it cannot answer the simple operator question: “show me my clients” 2. implementation drag teams cannot converge cleanly when the canonical client model is unclear 3. architectural debt new features get bolted onto mock data, partial tables, or analytics-first surfaces instead of a stable operational CRM spine The team cannot work around this forever because every adjacent feature depends on the client graph: - QD score - reminders - visit history - transcripts - Oracle writebacks - campaign attribution - property matching ## System Vision The intended end state is: - CRM is a top-level module in Velocity - Oracle remains the analytical and action-recommendation surface beside it - every client becomes a `Client 360` dossier - imports are schema-agnostic at ingestion time and canonical after approval - AI participates in normalization, enrichment, and suggestion - human operators approve writebacks and high-risk changes - every important interaction becomes part of the same longitudinal client graph ## Core Design Lens The design lens is: **the database is built by AI, for AI, and supervised by humans** This clarifies that: - raw evidence should be preserved, not prematurely flattened away - structured projections should exist for operator speed - provenance matters as much as value This lens must not be allowed to distort the design into opaque automation. Human approval, auditability, and role boundaries still matter. ## First-Principles Architecture ### Principle 1: Operational CRM is not optional Velocity cannot replace Salesforce if the user cannot browse contacts, accounts, opportunities, tasks, and activity history as first-class surfaces. Tradeoff: - this requires a larger canonical data model earlier ### Principle 2: Oracle is an intelligence surface, not the only product shell Oracle should augment CRM through insights, writeback proposals, and analytical views. It should not absorb the entire operational system. Tradeoff: - this creates duplicate-looking client contexts unless shared contracts are defined cleanly ### Principle 3: Preserve raw evidence, then project it The system should retain imported rows, transcripts, logs, and enrichment blobs while also projecting them into normalized tables. Tradeoff: - more storage and more schema design work ### Principle 4: Legacy truth must be mapped, not wished away Current tables such as `leads`, `leads_intelligence`, `chat_logs`, and `omnichannel_logs` are not final truth, but they are real sources of migration. Tradeoff: - planning must include a migration posture before implementation ### Principle 5: Infrastructure truth must be singular Operator knowledge about Linux origin, ingress, ComfyUI, and GPU NVMe policy must live in one canonical founder-owned reference. Tradeoff: - older docs must explicitly become secondary references ## Functional Architecture and Key Roles ### Founder CRM module - purpose: operational home for contacts, accounts, opportunities, activities, imports, and client 360 - inputs: canonical CRM and interaction graph data - outputs: operator actions, tasks, notes, updates, approvals - hard boundary: does not own low-level Oracle generation or Comfy runtime ### Oracle - purpose: analytical canvas, insight generation, writeback proposal generation - inputs: canonical client graph, inventory, tasks, events - outputs: views, recommendations, writeback proposals - hard boundary: not the only CRM shell ### NemoClaw / import intelligence - purpose: assist mapping, normalization, enrichment, and suggestion - inputs: raw import blobs, source profiles, policy rules, canonical schemas - outputs: proposed structured records, confidence scores, unresolved fields - hard boundary: may propose, must not silently commit high-risk changes ### Sentinel / perception layer - purpose: produce behavioral and perception-linked intelligence - inputs: perception sessions, room events, related media metadata - outputs: QD-related projections and evidence events - hard boundary: does not become the CRM system itself ## Data Model and Interfaces Major artifacts this planning effort depends on: - raw import batch - mapping manifest - canonical client entity set - interaction bundle - transcript bundle - QD timeline - Oracle writeback proposal - approval event - client 360 aggregate Each artifact needs: - stable identity - source provenance - producer/consumer ownership - lifecycle state ## Interaction and Workflow Description Standard founder-target workflow: 1. operator imports a CSV or connects an export source 2. raw batch is stored with provenance 3. mapping is proposed 4. NemoClaw proposes normalization and enrichment 5. operator approves or corrects 6. canonical CRM records are created or updated 7. Oracle and downstream modules read from the canonical graph 8. future interactions keep enriching the same dossier Failure handling: - unmapped columns remain unresolved, not discarded - ambiguous joins become approval tasks - high-risk merges become explicit review events ## Improvements and Recommendations - define CRM as a top-level module now - better because it answers the core customer question directly - cost is larger planning scope - separate raw evidence from normalized records - better because AI and humans can both work with the data safely - cost is more complex storage design - treat current repo tables as migration feeders - better because it respects reality and prevents destructive redesign - cost is migration planning overhead ## Migration and Fork Strategy Reuse: - current backend runtime and auth base - Oracle runtime - Sentinel runtime - current polished pipeline/detail UI building blocks Fork or redesign: - CRM data model - import architecture - operational CRM navigation - inventory canonical persistence Do not inherit as final truth: - mock frontend inventory and CRM data - the assumption that `leads` is the final client model ## What This Means for Project Velocity If this plan is followed: - the product becomes easier to explain - future modules gain a canonical source of client truth - demos become safer - owner boundaries become clearer Still out of scope in this planning pass: - code migration execution - full production rollout of the new CRM module - final approval of every table and route ## Recommended Initial Scope Initial founder planning scope: - reconciliation matrix - infra/operator truth - CRM product architecture - canonical domain model - import architecture - synthetic client graph generation brief - monolithic truth artifact skeleton and first chapter set ## Open Questions - how aggressively should old lead tables be merged versus wrapped - which Oracle views should become CRM-adjacent subtabs first - which existing frontend components can be reused directly for CRM lists and detail pages - what approval UX should govern high-risk merges and inferred identities ## Bottom Line Velocity does not need another disconnected capability. It needs a canonical client system that the rest of the product can orbit. The founder planning layer exists to define that system cleanly enough that future implementation stops drifting and starts compounding.