Project_Velocity/.Agent Context/Project Velocity Monolithic Truth.md

# Project Velocity Monolithic Truth

**Date:** 2026-04-18  
**Status:** Draft, appendable  
**Owner:** Sagnik  
**Reviewers:** Sayan, Sourik  
**Scope:** Founder-owned monolithic reference for the whole Project Velocity system  
**Purpose:** Provide a single chaptered artifact that explains what Project Velocity is, how it works, where it runs, what exists today, and what still needs approval.  
**Decision Boundary:** This document consolidates planning and current truth. It should be updated iteratively as subsystem plans are approved.

## How To Use This Document

- read the chapter you need
- use chapter-local references to drill into the founder pack or other Sprint 1 packs
- treat this artifact as the single onboarding reference once its chapters are mature

---

## Chapter 1. Project Thesis and User Problem

Project Velocity is being built as an AI-native operating system for premium real-estate sales teams. The thesis is that high-value property sales are not just about listings and reminders; they are about memory, timing, behavior, attention, inference, and orchestration across many channels.

The target user does not want a flat CRM. They want a system that can remember:

- who a client is
- what they want
- what they said
- how their interest evolved
- what property fits them
- when to act next

The current gap is not infrastructure. The current gap is canonical product truth, especially around CRM, imports, and the unified client graph.

---

## Chapter 2. Runtime Topology and Infra Truth

Current canonical operator truth:

- Linux origin box: `192.168.1.2`
- public ingress: stable edge and reverse proxy layer
- Comfy public ingress: `https://comfy.desineuron.in`
- GPU worker role: ComfyUI and heavy model execution

Non-negotiables:

- never use GPU public IP directly
- always use NVMe on the GPU box for model/runtime storage
- Linux box hosts application/backend/storage concerns
- GPU box hosts ComfyUI and heavyweight generation workloads

Current Comfy endpoint family:

- `/`
- `/prompt`
- `/history/{prompt_id}`
- `/queue`
- `/upload/image`

Detailed operator truth lives in:

- `Sprint 1/Founder CRM and Platform Delivery Pack/15 - Infrastructure and Operator Truth_ Linux Ingress GPU Comfy.md`

---

## Chapter 3. Product Module Map

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

- Dashboard
- Oracle
- Sentinel
- Inventory
- Catalyst
- Settings

Missing but required next:

- CRM as a top-level module

Planned CRM subnavigation:

- Contacts
- Accounts
- Opportunities
- Tasks
- Activity / Communications
- Imports
- Client 360
- Reports / Dashboards

---

## Chapter 4. Oracle

Oracle already exists as a real analytical and action-oriented surface. It is not a mock concept. It has:

- backend routes
- canvas runtime
- services for prompts, policy, collaboration, and data access
- frontend canvas and prompt rail

Oracle should remain:

- the intelligence surface
- the analytical canvas
- the writeback proposal generator

Oracle should not become:

- the only CRM shell

Planned Oracle CRM-adjacent subtabs:

- Oracle Canvas
- CRM Intelligence
- Import Review
- Client 360

---

## Chapter 5. CRM and Client 360

This is the founder-side missing center of gravity.

Current truth:

- CRM exists in partial backend and frontend forms
- lead and chat routes exist
- some CRM and Oracle UI pieces are polished
- there is still no canonical top-level CRM shell

Target truth:

- CRM becomes a top-level module
- every client becomes a `Client 360` dossier
- contacts, accounts, opportunities, tasks, and interactions become operational surfaces
- Oracle augments CRM instead of replacing it

Client 360 should aggregate:

- identity
- organization/account links
- opportunity state
- communication history
- reminders/tasks
- property interests
- QD trends
- Oracle insights

---

## Chapter 6. Sentinel / CCTV / Perception

Sentinel and related perception work already exist in meaningful form. The broader role of this subsystem is to produce intelligence that can enrich the client graph rather than remain isolated.

Relevant evidence and event classes include:

- perception sessions
- CCTV-linked events
- vehicle events / number plate references
- room-level or visit-level behavioral indicators
- QD-related signals

The founder planning direction is to map this material into the canonical `intel_*` domain so it becomes usable within CRM and Client 360.

---

## Chapter 7. Catalyst / Agents / Workflows

Catalyst and agent-related subsystems are already meaningful parts of the repo. The founder-side implication is that client intelligence, campaign execution, and future NemoClaw actions all need one stable customer graph to target.

Planned governance domain:

- `workflow_actions`
- `workflow_branches`
- `workflow_approvals`
- `workflow_writebacks`
- `workflow_agent_runs`
- `workflow_policy_decisions`

This keeps AI and automation powerful while preserving auditability.

---

## Chapter 8. Inventory

Inventory has product surface presence today, but not yet canonical persistence truth.

Current truth:

- polished inventory UI exists
- raw onboarding and catalog assets exist
- inventory persistence is still not fully canonical

Target domain:

- `inventory_projects`
- `inventory_units`
- `inventory_pricing_history`
- `inventory_availability`
- `inventory_media`
- `inventory_location_index`
- `inventory_import_jobs`

Inventory matters to CRM because every serious lead must connect to actual project and unit interest, not generic notes.

---

## Chapter 9. Identity and Access

The repo already contains `users_and_roles`, so user and role infrastructure is not missing. What is missing is the approved target structure for a longer-lived platform model.

Planned target:

- `core_users`
- `core_roles`
- `core_permissions`
- `core_role_assignments`
- `core_sessions`
- `core_audit_events`

This chapter will later align with Sayan’s admin/control surfaces.

---

## Chapter 10. Data Fabric, QD Score, and Intelligence Graph

The canonical design direction is:

- preserve raw evidence
- project structured truth from it
- keep provenance attached

The main missing domain from the founder’s original DB list is the interaction/evidence graph:

- `intel_interactions`
- `intel_messages`
- `intel_calls`
- `intel_call_recordings`
- `intel_transcripts`
- `intel_emails`
- `intel_whatsapp_threads`
- `intel_visits`
- `intel_reminders`
- `intel_qd_scores`
- `intel_qd_timeseries`
- `intel_vehicle_events`
- `intel_perception_events`
- `intel_cctv_links`
- `intel_blob_store_index`

This is the part of the database that makes Velocity “of the AI, for the AI” while staying reviewable by humans.

---

## Chapter 11. Communication Capture and Transcripts

The intended product direction includes:

- WhatsApp messages
- WhatsApp voice calls and transcripts
- email threads
- reminders and follow-ups
- future broader communication integrations

The planning rule is that communication artifacts are not just notes. They are structured evidence:

- preserved raw
- transcript-linked
- tied to client records
- usable for tasks, QD, and Oracle insights

---

## Chapter 12. Import Architecture

The import system should be:

- CSV-first
- mapping-driven
- schema-agnostic at ingestion time
- canonical after approval

Planned import pipeline:

1. raw upload
2. header detection
3. source profile selection
4. mapping manifest generation
5. NemoClaw-assisted normalization and enrichment
6. operator review
7. canonical commit

Source profiles to plan first:

- Salesforce-style CRM export
- HubSpot CRM export
- Jira-style CSV export
- generic brokerage spreadsheet

---

## Chapter 13. Deployment and Operations

Future CRM implementation must fit the topology that already exists. It should not invent a parallel system.

Release gates for the future CRM phase must include:

- technical integrity
- governance integrity
- operational integrity
- sales integrity

This chapter should continue to absorb operational truth from the founder pack over time.

---

## Chapter 14. Open Gaps, Approvals, and Next Decisions

Current open gaps:

- top-level CRM module implementation
- canonical schema approval
- inventory persistence approval
- import review UX approval
- Oracle-to-CRM writeback governance approval

Current approved founder defaults:

- CRM is top-level
- Oracle is adjacent
- CSV-first import is the correct initial path
- legacy tables are migration feeders
- interaction/evidence and workflow/governance are required DB domains in addition to the founder’s original list

Next documents to consult:

- `Sprint 1/Founder CRM and Platform Delivery Pack/*`
- especially the reconciliation matrix, infra truth doc, DB/root API spec, and synthetic data brief

---

## Bottom Line

Project Velocity already contains meaningful product and runtime work. The reason it still feels incomplete is not that nothing exists. It is that the core system of record for clients, interactions, imports, and product ownership has not yet been unified. This monolithic truth artifact exists to fix that, chapter by chapter, until the whole platform becomes legible.