Project_Velocity/.Agent Context/Sprint 1/Founder CRM and Platform Delivery Pack/01 - First Principles_ Founder CRM and Platform Planning.md

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.