Project_Velocity/.Agent Context/Codebase Analysis Docs/Codebase Analysis v1.2.md

# Codebase Analysis v1.2.md

## Table of Contents / Chapters

### 1. Overview
- Introduction to Project Velocity and its purpose
- Core principles and approach

### 2. Architectural Mapping
- Overall System Architecture (Mermaid diagram)
- File Dependency Graph (Mermaid diagram)  
- Data Flow Architecture (Mermaid diagram)

### 3. Logic Decomposition
- Authentication & Authorization
- CRM Data Model
- Sentinel Biometric Intelligence
- Oracle Natural Language Intelligence
- Catalyst Marketing Orchestration
- Infrastructure & Deployment

### 4. Connectivity Matrix
- Component interconnections and data flow
- Interconnection rationale

### 5. First-Principles Guide
- Core Concept: AI-Augmented Sales Intelligence
- Why Real Estate Specifically?
- Principle 1: Data Sovereignty First
- Principle 2: Real-Time Perception Matters
- Principle 3: Intelligence Through Conversation
- Principle 4: Visual Storytelling Drives Sales
- Principle 5: Revision Control for Business Logic
- Design Philosophy: Production-Ready Craft
- Why This Architecture Succeeds

### 6. API Endpoints Reference
- Authentication Endpoints
- CRM Endpoints
- Analytics Endpoints
- Oracle AI Intelligence Endpoints
  - Oracle Canvas Management (v1)
  - Oracle Template Management
- Sentinel Biometric Intelligence Endpoints
- Catalyst Marketing Orchestration Endpoints
- Vault Trackable Links Endpoints
- CCTV Surveillance Integration Endpoints
- Video Scene Mapping Endpoints
- Marketing Videos Endpoints
- Mobile Edge Communication Endpoints
- Inventory Management Endpoints
- Admin Surface Control Endpoints
- CRM Canonical Data Endpoints
- Runtime LLM Endpoints
- Infrastructure Notes

## Overview

Project Velocity is an on-prem real estate operating system designed for high-value property sales. It combines a premium WebOS, an iPad field app, a FastAPI neural core, ComfyUI-based media generation, and biometric/sentiment-assisted sales intelligence. The system enables brokers to operate at the speed of AI while preserving control, provenance, and safety for customer and revenue-critical data.

This analysis provides a comprehensive understanding of the codebase from first principles, applying the Feynman Technique to distill complex implementations into intuitive concepts.

## Architectural Mapping

### Overall System Architecture

```mermaid
graph TB
    subgraph "User Interfaces"
        WebOS[Velocity WebOS<br/>React + TypeScript]
        iPad[iPad App<br/>Swift + MediaPipe]
    end
    
    subgraph "Core Backend"
        FastAPI[FastAPI Neural Core<br/>PostgreSQL + JWT Auth]
    end
    
    subgraph "AI Services"
        Oracle[The Oracle<br/>Natural Language Intelligence]
        Sentinel[The Sentinel<br/>Biometric Perception Engine]
        Catalyst[The Catalyst<br/>Marketing Campaign Orchestration]
        Comfy[ComfyUI / Dream Weaver<br/>Media Generation]
    end
    
    subgraph "Infrastructure"
        AWS[AWS GPU Workers<br/>NVIDIA GPUs]
        S3[S3 Asset Store<br/>Models + Media]
        Linux[Linux Control Surface<br/>On-prem Deployment]
    end
    
    WebOS --> FastAPI
    iPad --> FastAPI
    FastAPI --> Oracle
    FastAPI --> Sentinel
    FastAPI --> Catalyst
    Catalyst --> Comfy
    Comfy --> AWS
    Comfy --> S3
    FastAPI --> Linux
    
    style FastAPI fill:#e1f5fe
    style Oracle fill:#f3e5f5
    style Sentinel fill:#e8f5e8
    style Catalyst fill:#fff3e0
```

### File Dependency Graph

```mermaid
graph TD
    subgraph "Frontend (React/Vite)"
        App[App.tsx<br/>Routing & Auth]
        Store[useStore.ts<br/>Zustand State]
        Components[Components/<br/>Modules & UI]
        API[api.ts<br/>HTTP Client]
    end
    
    subgraph "Backend (FastAPI)"
        Main[main.py<br/>App Entry]
        Routers[routers/<br/>API Endpoints]
        Services[services/<br/>Business Logic]
        DB[db/<br/>Schema & Pool]
        Auth[auth/<br/>JWT & Users]
        Oracle[oracle/<br/>AI Intelligence]
    end
    
    subgraph "AI Infrastructure"
        Comfy[comfy_engine/<br/>Media Generation]
        Models[models/<br/>AI Models]
        Prompts[nemoclaw_prompts/<br/>LLM Templates]
    end
    
    subgraph "Deployment"
        Infra[infrastructure/<br/>Linux + AWS]
        Agents[agents/<br/>Orchestration]
    end
    
    App --> API
    API --> Main
    Main --> Routers
    Routers --> Services
    Services --> DB
    Services --> Auth
    Services --> Oracle
    Oracle --> Prompts
    Comfy --> Infra
    Infra --> Agents
    
    style Main fill:#e3f2fd
    style Oracle fill:#fce4ec
```

### Data Flow Architecture

```mermaid
flowchart LR
    User[User Input] --> UI[WebOS/iPad UI]
    UI --> API[FastAPI Endpoints]
    API --> Auth[JWT Authentication]
    API --> Policy[Policy Engine<br/>Authorization]
    API --> LLM[Nemoclaw LLM<br/>Reasoning & Planning]
    LLM --> Query[SQL Generation<br/>Safe Queries]
    Query --> DB[(PostgreSQL<br/>CRM + Intelligence)]
    DB --> Results[Query Results]
    Results --> Viz[Visualization<br/>Components]
    Viz --> Canvas[Oracle Canvas<br/>Persistent Views]
    Canvas --> UI
    
    Sentinel[Sentinel Biometric] --> WS[WebSocket<br/>Real-time]
    WS --> Perception[Face Analysis<br/>MediaPipe]
    Perception --> QD[QD Scoring<br/>NemoClaw]
    QD --> DB
    
    Catalyst[Catalyst Marketing] --> Comfy[ComfyUI<br/>Media Generation]
    Comfy --> S3[S3 Assets]
    Comfy --> GPU[AWS GPUs]
    
    style DB fill:#fff9c4
    style LLM fill:#e8f5e8
    style Comfy fill:#fce4ec
```

## Logic Decomposition

### Authentication & Authorization

**What:** Secure access control for all system functions
**How:** JWT tokens with role-based permissions (ADMIN, SALES_DIRECTOR, SENIOR_BROKER, JUNIOR_BROKER)
**Why:** Real estate involves sensitive client data; strict access prevents unauthorized sales interference

**Key Implementation:**
- `backend/auth/dependencies.py`: JWT validation, user extraction, role enforcement
- `main.py`: Login endpoint with password hashing, user profile management
- Role hierarchy prevents junior brokers from approving high-value deals

### CRM Data Model

**What:** Canonical client and interaction records
**How:** PostgreSQL schema with leads, contacts, opportunities, interactions
**Why:** Real estate sales require accurate pipeline tracking and relationship history

**Key Tables:**
- `leads_intelligence`: Core lead data with QD scores and tags
- `omnichannel_logs`: All interactions (calls, emails, visits) with timestamps
- `crm_people/crm_leads`: Structured client relationships and deal stages

### Sentinel Biometric Intelligence

**What:** Real-time visitor sentiment analysis for showroom engagement
**How:** Browser webcam + MediaPipe face landmarking → blend shapes → QD scoring
**Why:** Human emotion drives buying decisions; AI detects subtle cues brokers miss

**Execution Flow:**
1. Browser captures video stream
2. MediaPipe extracts facial landmarks (68 points)
3. Blend shapes calculated (brow furrow, smile intensity, etc.)
4. NemoClaw LLM scores 1-100 QD (Qualification Desire)
5. Real-time dashboard updates for brokers

**Key Decision:** Browser-side processing preserves privacy (no video leaves client device)

### Oracle Natural Language Intelligence

**What:** AI-powered data analysis through conversational queries
**How:** Natural language → SQL planning → visualization components → canvas
**Why:** Brokers shouldn't need SQL knowledge; AI translates business questions to insights

**Architecture Layers:**
- **Prompt Orchestrator:** Decomposes complex requests into sub-queries
- **Natural DB Agent:** Schema introspection + safe SQL generation
- **Canvas Service:** Persistent visual workspaces with revision history
- **Collaboration:** Fork/merge workflows for team coordination

**Why Canvas?** Unlike transient chat responses, canvases persist as living documents

### Catalyst Marketing Orchestration

**What:** Automated campaign creation and asset generation
**How:** Meta Ads API integration + ComfyUI media workflows
**Why:** Luxury real estate needs high-quality visuals; manual creation is too slow

**Workflow:**
1. Campaign parameters → Meta API calls
2. Creative assets → ComfyUI (Dream Weaver, Wan 2.2, Qwen poster generation)
3. GPU processing on AWS → S3 storage
4. Performance tracking back to CRM

### Infrastructure & Deployment

**What:** Production-ready on-prem + cloud hybrid deployment
**How:** Linux control surface + AWS GPU workers + stable ingress
**Why:** Real estate firms demand data sovereignty; cloud-only solutions unacceptable

**Key Components:**
- **Ingress:** Caddy on EC2 t4g.micro with TLS termination
- **Backend:** Linux systemd services for FastAPI, ComfyUI, LLM runtime
- **GPU:** AWS managed instances for media generation
- **Assets:** S3 for model storage, NVMe for fast access

## Connectivity Matrix

| Component | Inputs | Outputs | Dependencies | Protocols |
|-----------|--------|---------|--------------|-----------|
| WebOS Frontend | User actions, API responses | UI renders, API calls | FastAPI backend | HTTP/WS, JWT |
| iPad App | Camera feeds, user input | Biometric data, inventory scans | FastAPI backend | HTTP/WS |
| FastAPI Core | API requests, WS connections | DB queries, AI responses | PostgreSQL, Redis (future) | SQL, HTTP |
| Oracle Engine | Natural language prompts | Canvas components | NemoClaw LLM, PostgreSQL | Internal API |
| Sentinel Engine | Webcam streams | QD scores, alerts | MediaPipe, NemoClaw | WS real-time |
| Catalyst Engine | Campaign specs | Ad creatives, assets | Meta API, ComfyUI | HTTP, S3 |
| ComfyUI | Generation requests | Images/videos | GPU workers, S3 | Internal queue |
| PostgreSQL | SQL queries | Structured data | - | SQL |
| AWS GPUs | Media jobs | Generated assets | ComfyUI workflows | SSH/tunnel |

**Interconnection Rationale:**
- **WebOS ↔ Backend:** Thin client architecture; all business logic server-side for security
- **Backend ↔ AI Services:** Modular design; each AI component (Oracle, Sentinel, Catalyst) operates independently but shares auth/policy
- **AI Services ↔ DB:** Direct SQL access with row-level security; no ORM abstraction to maintain performance
- **Infrastructure:** Hybrid on-prem/cloud; sensitive data stays on-prem, compute-intensive tasks use cloud GPUs

## First-Principles Guide

### Core Concept: AI-Augmented Sales Intelligence

At its foundation, Project Velocity operates on the principle that human sales professionals excel at relationship-building and deal-closing, while AI excels at pattern recognition, data synthesis, and repetitive analysis. The system doesn't replace brokers—it amplifies their capabilities by providing real-time insights they couldn't otherwise access.

**Why Real Estate Specifically?**
- High-value transactions ($M+ deals) with long sales cycles (months)
- Emotional decision-making influenced by subtle cues
- Complex data relationships (properties, buyers, markets, timing)
- Regulatory compliance requirements
- Need for visual storytelling (luxury properties)

### Principle 1: Data Sovereignty First

**Fundamental Truth:** Real estate firms own their client relationships. Project Velocity runs on-premise or in tenant-controlled cloud to maintain this ownership.

**Implementation:** Linux-based deployment with optional AWS GPU extensions. All client data remains within tenant boundaries; only anonymous model requests leave for AI processing.

### Principle 2: Real-Time Perception Matters

**Fundamental Truth:** Buying decisions happen in moments of emotional connection. Project Velocity captures these moments through biometric analysis.

**Implementation:** Sentinel uses facial expression analysis to score "Qualification Desire" (QD) on a 1-100 scale, alerting brokers to engagement spikes during property tours.

### Principle 3: Intelligence Through Conversation

**Fundamental Truth:** Sales professionals think in business terms, not database queries. The Oracle translates natural language into structured analytics.

**Implementation:** Users ask "Show me whale leads from Dubai this quarter" and receive visual dashboards. The system plans safe SQL queries, executes them, and renders results as persistent canvas components.

### Principle 4: Visual Storytelling Drives Sales

**Fundamental Truth:** Luxury properties sell through aspiration and emotion. AI-generated media must be photorealistic and brand-consistent.

**Implementation:** ComfyUI workflows (Dream Weaver, Wan 2.2) create property visualizations. Catalyst orchestrates campaigns with generated assets automatically uploaded to Meta Ads.

### Principle 5: Revision Control for Business Logic

**Fundamental Truth:** Sales strategies evolve through collaboration and iteration. Oracle canvases use Git-like branching for analytical workflows.

**Implementation:** Canvas pages support forks, merge requests, and revision history. Brokers can experiment with analysis approaches without breaking production views.

### Design Philosophy: Production-Ready Craft

Project Velocity follows "experienced engineer" principles:
- **Error Handling:** No silent failures; all errors surface useful messages
- **Type Safety:** TypeScript frontend, typed Python backend
- **Performance:** Async everywhere, connection pooling, efficient queries
- **Security:** JWT auth, role-based access, input validation
- **Observability:** Structured logging, health checks, WebSocket monitoring
- **Maintainability:** Clear separation of concerns, comprehensive documentation

### Why This Architecture Succeeds

1. **Modular AI Services:** Each intelligence component (Oracle, Sentinel, Catalyst) operates independently, allowing incremental improvement and specialized optimization.

2. **Hybrid Infrastructure:** Combines on-prem reliability with cloud scalability. Sensitive CRM data stays local; compute-intensive media generation uses managed GPUs.

3. **Real-Time Integration:** WebSockets enable live updates across all surfaces. Brokers see lead scoring changes instantly, dashboard metrics update in real-time.

4. **Business Logic in Code:** Revenue-critical workflows (lead qualification, campaign approval, deal closing) are explicit code paths, not AI hallucinations.

5. **User-Centric Design:** The WebOS feels like a native application, not a bolted-on AI interface. Familiar patterns (canvases, dashboards, forms) reduce training time.

This architecture transforms real estate sales from intuition-driven processes into data-augmented, AI-accelerated operations while preserving the human elements that drive luxury transactions.

## API Endpoints Reference

This section provides a comprehensive catalog of all API endpoints exposed by the Project Velocity backend, organized by functional module. Each endpoint includes the HTTP method, URI path, absolute HTTPS URL, and a brief description of its functionality. This serves as the definitive source of truth for the project's routing and interface architecture.

### Authentication Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/auth/login | https://velocity.desineuron.in/api/auth/login | Authenticate a user with email/password and return JWT token |
| GET | /api/auth/me | https://velocity.desineuron.in/api/auth/me | Get current authenticated user's profile information |
| GET | /api/auth/users | https://velocity.desineuron.in/api/auth/users | List all active users in the system |
| POST | /api/auth/profile/avatar | https://velocity.desineuron.in/api/auth/profile/avatar | Upload and update user's profile avatar image |

### CRM Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/leads | https://velocity.desineuron.in/api/leads | List leads with pagination and filtering |
| GET | /api/leads/{lead_id} | https://velocity.desineuron.in/api/leads/{lead_id} | Get detailed information for a specific lead |
| GET | /api/kanban/board | https://velocity.desineuron.in/api/kanban/board | Retrieve the kanban board view of leads by stage |
| GET | /api/chat-logs | https://velocity.desineuron.in/api/chat-logs | List chat logs for leads with optional lead filtering |
| GET | /api/leads/demographics | https://velocity.desineuron.in/api/leads/demographics | Get demographic analytics for leads (source, qualification) |

### Analytics Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/analytics/sentiment-scatter | https://velocity.desineuron.in/api/analytics/sentiment-scatter | Get scatter plot data for sentiment analysis |

### Oracle AI Intelligence Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/oracle/health | https://velocity.desineuron.in/api/oracle/health | Check Oracle system health and MCP tool availability |
| GET | /api/oracle/data-health | https://velocity.desineuron.in/api/oracle/data-health | Get data health metrics for database tables |
| GET | /api/oracle/schema-catalog | https://velocity.desineuron.in/api/oracle/schema-catalog | Retrieve schema catalog for database introspection |
| POST | /api/oracle/query | https://velocity.desineuron.in/api/oracle/query | Execute natural language query against database |
| GET | /api/oracle/mcp/tools | https://velocity.desineuron.in/api/oracle/mcp/tools | List available MCP tools for execution |
| POST | /api/oracle/mcp/execute | https://velocity.desineuron.in/api/oracle/mcp/execute | Execute an MCP tool with given query |
| POST | /api/oracle/workflow/preview | https://velocity.desineuron.in/api/oracle/workflow/preview | Preview workflow plan for a natural language prompt |

#### Oracle Canvas Management (v1)

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/oracle/v1/canvas/pages | https://velocity.desineuron.in/api/oracle/v1/canvas/pages | Create a new Oracle canvas page |
| GET | /api/oracle/v1/canvas/pages | https://velocity.desineuron.in/api/oracle/v1/canvas/pages | List user's Oracle canvas pages |
| GET | /api/oracle/v1/canvas/pages/{page_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id} | Get a specific canvas page |
| PUT | /api/oracle/v1/canvas/pages/{page_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id} | Update a canvas page |
| DELETE | /api/oracle/v1/canvas/pages/{page_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id} | Delete a canvas page |
| POST | /api/oracle/v1/canvas/pages/{page_id}/fork | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/fork | Create a fork of a canvas page |
| POST | /api/oracle/v1/canvas/pages/{page_id}/merge | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/merge | Merge changes into a canvas page |
| GET | /api/oracle/v1/canvas/pages/{page_id}/revisions | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions | List revisions for a canvas page |
| POST | /api/oracle/v1/canvas/pages/{page_id}/revisions | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions | Create new revision for a canvas page |
| GET | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id} | Get specific revision |
| PUT | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id} | Update a revision |
| DELETE | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id} | Delete a revision |
| GET | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components | List components in a revision |
| POST | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components | Add component to revision |
| PUT | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components/{component_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components/{component_id} | Update component |
| DELETE | /api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components/{component_id} | https://velocity.desineuron.in/api/oracle/v1/canvas/pages/{page_id}/revisions/{revision_id}/components/{component_id} | Delete component |

#### Oracle Template Management

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/oracle/template-chapters | https://velocity.desineuron.in/api/oracle/template-chapters | List Oracle template chapters |
| POST | /api/oracle/template-chapters | https://velocity.desineuron.in/api/oracle/template-chapters | Create new template chapter |
| GET | /api/oracle/template-subchapters | https://velocity.desineuron.in/api/oracle/template-subchapters | List Oracle template subchapters |
| POST | /api/oracle/template-subchapters | https://velocity.desineuron.in/api/oracle/template-subchapters | Create new template subchapter |
| GET | /api/oracle/component-templates | https://velocity.desineuron.in/api/oracle/component-templates | List Oracle component templates |
| POST | /api/oracle/component-templates | https://velocity.desineuron.in/api/oracle/component-templates | Create new component template |
| GET | /api/oracle/component-templates/{template_id} | https://velocity.desineuron.in/api/oracle/component-templates/{template_id} | Get specific component template |
| POST | /api/oracle/component-templates/{template_id}/seed | https://velocity.desineuron.in/api/oracle/component-templates/{template_id}/seed | Add seed example to template |
| GET | /api/oracle/component-templates/{template_id}/seed | https://velocity.desineuron.in/api/oracle/component-templates/{template_id}/seed | List seed examples for template |
| POST | /api/oracle/component-templates/synthetic-jobs | https://velocity.desineuron.in/api/oracle/component-templates/synthetic-jobs | Submit synthetic template generation job |

### Sentinel Biometric Intelligence Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| WebSocket | /api/sentinel/ws/notifications | wss://velocity.desineuron.in/api/sentinel/ws/notifications | Real-time notifications WebSocket |
| WebSocket | /api/sentinel/ws/perception | wss://velocity.desineuron.in/api/sentinel/ws/perception | Biometric perception data WebSocket |
| POST | /api/sentinel/consent | https://velocity.desineuron.in/api/sentinel/consent | Record biometric consent for lead |
| POST | /api/sentinel/session/complete | https://velocity.desineuron.in/api/sentinel/session/complete | Close a perception session and finalize QD score |
| POST | /api/sentinel/tag-lead | https://velocity.desineuron.in/api/sentinel/tag-lead | Apply NemoClaw lead tagging to CRM lead |
| GET | /api/sentinel/qd-score/{lead_id} | https://velocity.desineuron.in/api/sentinel/qd-score/{lead_id} | Get current QD score for a lead |

### Catalyst Marketing Orchestration Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/catalyst/campaigns/create | https://velocity.desineuron.in/api/catalyst/campaigns/create | Bulk create Meta ad campaigns |
| POST | /api/catalyst/creative/sync | https://velocity.desineuron.in/api/catalyst/creative/sync | Upload ComfyUI assets to Meta |
| GET | /api/catalyst/insights/realtime | https://velocity.desineuron.in/api/catalyst/insights/realtime | Poll Meta Ads Insights API |
| POST | /api/catalyst/audiences/lookalike | https://velocity.desineuron.in/api/catalyst/audiences/lookalike | Push CRM leads to Meta Custom Audience |
| POST | /api/catalyst/auth/meta | https://velocity.desineuron.in/api/catalyst/auth/meta | OAuth token acquisition for Meta |

### Vault Trackable Links Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/vault/generate-link | https://velocity.desineuron.in/api/vault/generate-link | Generate trackable URL for shared asset |
| GET | /vault/{tracking_hash} | https://velocity.desineuron.in/vault/{tracking_hash} | Public access to trackable vault link (no auth required) |

### CCTV Surveillance Integration Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/cctv/event | https://velocity.desineuron.in/api/cctv/event | Ingest CCTV frame event from RTSP/ONVIF bridge |
| POST | /api/cctv/finalize-auto-mode | https://velocity.desineuron.in/api/cctv/finalize-auto-mode | Match or create lead after auto-mode session |

### Video Scene Mapping Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/scenes/upload | https://velocity.desineuron.in/api/scenes/upload | Upload CSV scene map for marketing video |
| GET | /api/scenes/{video_asset_id} | https://velocity.desineuron.in/api/scenes/{video_asset_id} | Get scene map for specific video asset |

### Marketing Videos Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/videos/marketing | https://velocity.desineuron.in/api/videos/marketing | List marketing videos available for Sentinel sessions |

### Mobile Edge Communication Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/mobile-edge/events | https://velocity.desineuron.in/api/mobile-edge/events | List communication events for a lead |
| POST | /api/mobile-edge/events | https://velocity.desineuron.in/api/mobile-edge/events | Log new communication event |
| GET | /api/mobile-edge/memory | https://velocity.desineuron.in/api/mobile-edge/memory | List memory facts for a lead |
| POST | /api/mobile-edge/imports | https://velocity.desineuron.in/api/mobile-edge/imports | Operator-assisted import of recording/note |
| POST | /api/mobile-edge/notes | https://velocity.desineuron.in/api/mobile-edge/notes | Quick note attachment to lead |
| GET | /api/mobile-edge/calendar | https://velocity.desineuron.in/api/mobile-edge/calendar | Calendar events for authenticated user |
| POST | /api/mobile-edge/calendar | https://velocity.desineuron.in/api/mobile-edge/calendar | Create calendar event |
| PATCH | /api/mobile-edge/calendar/{calendar_event_id} | https://velocity.desineuron.in/api/mobile-edge/calendar/{calendar_event_id} | Update calendar event |
| DELETE | /api/mobile-edge/calendar/{calendar_event_id} | https://velocity.desineuron.in/api/mobile-edge/calendar/{calendar_event_id} | Cancel calendar event |
| GET | /api/mobile-edge/transcripts/{event_id} | https://velocity.desineuron.in/api/mobile-edge/transcripts/{event_id} | Transcript segments for event |
| GET | /api/mobile-edge/insights/{lead_id} | https://velocity.desineuron.in/api/mobile-edge/insights/{lead_id} | Insight recommendations for lead |
| POST | /api/mobile-edge/insights/{recommendation_id}/act | https://velocity.desineuron.in/api/mobile-edge/insights/{recommendation_id}/act | Act on or dismiss insight |
| GET | /api/mobile-edge/alerts | https://velocity.desineuron.in/api/mobile-edge/alerts | Active alerts for authenticated user |
| POST | /api/mobile-edge/session | https://velocity.desineuron.in/api/mobile-edge/session | Register surface session heartbeat |

### Inventory Management Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/inventory/import-batches | https://velocity.desineuron.in/api/inventory/import-batches | Create inventory import batch |
| GET | /api/inventory/import-batches | https://velocity.desineuron.in/api/inventory/import-batches | List import batches |
| GET | /api/inventory/import-batches/{batch_id} | https://velocity.desineuron.in/api/inventory/import-batches/{batch_id} | Get batch status |
| POST | /api/inventory/properties | https://velocity.desineuron.in/api/inventory/properties | Create single property |
| GET | /api/inventory/properties | https://velocity.desineuron.in/api/inventory/properties | List inventory properties |
| GET | /api/inventory/properties/{property_id} | https://velocity.desineuron.in/api/inventory/properties/{property_id} | Get property details |
| PATCH | /api/inventory/properties/{property_id} | https://velocity.desineuron.in/api/inventory/properties/{property_id} | Update property |
| DELETE | /api/inventory/properties/{property_id} | https://velocity.desineuron.in/api/inventory/properties/{property_id} | Archive property |
| POST | /api/inventory/properties/{property_id}/media | https://velocity.desineuron.in/api/inventory/properties/{property_id}/media | Attach media to property |
| GET | /api/inventory/properties/{property_id}/media | https://velocity.desineuron.in/api/inventory/properties/{property_id}/media | List media for property |
| DELETE | /api/inventory/media/{media_asset_id} | https://velocity.desineuron.in/api/inventory/media/{media_asset_id} | Remove media asset |

### Admin Surface Control Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| GET | /api/admin-surface/health | https://velocity.desineuron.in/api/admin-surface/health | System health overview |
| GET | /api/admin-surface/queues | https://velocity.desineuron.in/api/admin-surface/queues | Queue depth snapshot |
| GET | /api/admin-surface/installs | https://velocity.desineuron.in/api/admin-surface/installs | Surface session/install overview |
| POST | /api/admin-surface/actions | https://velocity.desineuron.in/api/admin-surface/actions | Submit admin action |
| GET | /api/admin-surface/actions | https://velocity.desineuron.in/api/admin-surface/actions | List admin action history |
| GET | /api/admin-surface/actions/{action_event_id} | https://velocity.desineuron.in/api/admin-surface/actions/{action_event_id} | Get specific admin action |
| GET | /api/admin-surface/logs | https://velocity.desineuron.in/api/admin-surface/logs | Recent Oracle audit event log |
| GET | /api/admin-surface/templates | https://velocity.desineuron.in/api/admin-surface/templates | Template catalog admin view |
| POST | /api/admin-surface/templates/{template_id}/publish | https://velocity.desineuron.in/api/admin-surface/templates/{template_id}/publish | Publish template |
| POST | /api/admin-surface/templates/{template_id}/archive | https://velocity.desineuron.in/api/admin-surface/templates/{template_id}/archive | Archive template |
| GET | /api/admin-surface/template-chapters | https://velocity.desineuron.in/api/admin-surface/template-chapters | List template chapters (admin) |
| GET | /api/admin-surface/synthetic-jobs | https://velocity.desineuron.in/api/admin-surface/synthetic-jobs | List synthetic generation jobs |
| POST | /api/admin-surface/synthetic-jobs/{job_id}/cancel | https://velocity.desineuron.in/api/admin-surface/synthetic-jobs/{job_id}/cancel | Cancel synthetic job |

### CRM Canonical Data Endpoints

| Method | Path | Absolute URL | Description |
|--------|------|--------------|-------------|
| POST | /api/crm/imports | https://velocity.desineuron.in/api/crm/imports | Upload CSV batch for import |
| GET | /api/crm/imports | https://velocity.desineuron.in/api/crm/imports | List import batches |
| GET | /api/crm/imports/{batch_id} | https://velocity.desineuron.in/api/crm/imports/{batch_id} | Get batch detail and proposals |
| PUT | /api/crm/imports/{batch_id}/review-proposal | https://velocity.desineuron.in/api/crm/imports/{batch_id}/review-proposal | Review import proposal |
| POST | /api/crm/imports/{batch_id}/commit | https://velocity.desineuron.in/api/crm/imports/{batch_id}/commit | Commit approved proposals |
| GET | /api/crm/contacts | https://velocity.desineuron.in/api/crm/contacts | Canonical contact list with QD summary |
| POST | /api/crm/contacts | https://velocity.desineuron.in/api/crm/contacts | Create new contact |
| GET | /api/crm/contacts/{person_id} | https://velocity.desineuron.in/api/crm/contacts/{person_id} | Canonical contact detail |
| GET | /api/crm/client-360/{person_id} | https://velocity.desineuron.in/api/crm/client-360/{person_id} | Client 360 aggregated snapshot |
| GET | /api/crm/opportunities | https://velocity.desineuron.in/api/crm/opportunities | Opportunity pipeline list |
| GET | /api/crm/tasks | https://velocity.desineuron.in/api/crm/tasks | Reminder/task list |
| POST | /api/crm/tasks | https://velocity.desineuron.in/api/crm/tasks | Create new task |
| GET | /api/crm/kanban | https://velocity.desineuron.in/api/crm/kanban | Kanban board (canonical leads) |
| GET | /api/crm/qd/{person_id} | https://velocity.desineuron.in/api/crm/qd/{person_id} | QD score history for person |
| GET | /api/crm/client-data | https://velocity.desineuron.in/api/crm/client-data | List client data records |
| GET | /api/crm/client-data/{person_id} | https://velocity.desineuron.in/api/crm/client-data/{person_id} | Get client data for person |
| PATCH | /api/crm/client-data/{person_id} | https://velocity.desineuron.in/api/crm/client-data/{person_id} | Update client data |
| GET | /api/crm/client-data/{person_id}/timeline | https://velocity.desineuron.in/api/crm/client-data/{person_id}/timeline | Client data timeline |
| POST | /api/crm/client-data/{person_id}/tasks | https://velocity.desineuron.in/api/crm/client-data/{person_id}/tasks | Create task for client |

### Runtime LLM Endpoints

| Method | Path | Absolute URL | Description |
|---|---|---|---|
| GET | /api/runtime/llm/providers | https://velocity.desineuron.in/api/runtime/llm/providers | List configured LLM providers and models |
| POST | /api/runtime/llm/chat | https://velocity.desineuron.in/api/runtime/llm/chat | Execute single LLM chat completion |
| POST | /api/runtime/llm/batch | https://velocity.desineuron.in/api/runtime/llm/batch | Submit persisted LLM batch job |
| GET | /api/runtime/llm/jobs/{job_id} | https://velocity.desineuron.in/api/runtime/llm/jobs/{job_id} | Get batch job status |
| GET | /api/runtime/llm/jobs/{job_id}/results | https://velocity.desineuron.in/api/runtime/llm/jobs/{job_id}/results | Get batch job results |

### Infrastructure Notes

- **Caddy Reverse Proxy**: All endpoints are served through Caddy on port 443, proxying to FastAPI on localhost:8443 with TLS termination
- **Authentication**: JWT-based auth required for most endpoints (except public vault links)
- **WebSockets**: Real-time features use WebSocket connections for live updates
- **Role-Based Access**: Endpoints enforce role permissions (SENIOR_BROKER, ADMIN, etc.)
- **Tenant Isolation**: Multi-tenant architecture with tenant_id scoping
- **Audit Logging**: All mutations create immutable audit records
- **Health Checks**: System provides comprehensive health and queue monitoring endpoints

---

# v1.2 Audit Addendum: Definitive Source Of Truth

Date: 2026-04-29  
Purpose: Convert the existing broad analysis into a practical onboarding map for technical and non-technical stakeholders.  
Method: The audit below was derived from the current repository structure and key implementation files, including `README.md`, `backend/main.py`, `app/src/App.tsx`, backend route modules, Oracle services, CRM schemas, Comms schema, synthetic CRM assets, Comfy/Dream Weaver gateway code, and ingress infrastructure files.

## 1. Executive Summary In Plain English

Project Velocity is a private real-estate operating system. It is not just a CRM, not just a dashboard, and not just an AI demo. It is a coordinated system for turning real estate sales activity into structured intelligence.

The product answers one practical question:

> How can a real-estate team know which clients matter, what they want, when to act, and how to produce persuasive sales/marketing material quickly?

The system does this by combining five layers:

| Layer | Plain-English Role | Code Area |
| --- | --- | --- |
| WebOS frontend | The cockpit used by the team | `app/` |
| FastAPI backend | The traffic controller and business brain | `backend/` |
| PostgreSQL database | The memory of clients, properties, actions, and intelligence | `backend/db/*.sql`, runtime DB |
| AI/runtime services | The reasoning and generation layer | `backend/oracle/`, `backend/services/runtime_llm_service.py`, `comfy_engine/`, `dw_gateway_v2_min.py` |
| Infrastructure | The public routing, deployment, GPU workers, and recovery machinery | `infrastructure/desineuron_ingress/` |

For a non-technical reader, think of Velocity as a hotel concierge system for luxury real estate:

- The CRM remembers every guest, preference, conversation, objection, and next step.
- The Oracle lets managers ask questions in normal language.
- The Sentinel observes engagement signals during showroom experiences.
- The Catalyst produces campaign and staging assets.
- The Comms surface centralizes WhatsApp-like communication.
- The backend keeps all of this tied to the same client record.

For a technical reader, Velocity is:

- React 19 + Vite + TypeScript frontend.
- FastAPI backend with JWT auth, asyncpg/PostgreSQL, modular routers, WebSockets, and service layers.
- Canonical CRM/intelligence schema with synthetic CRM v2 seed assets.
- Oracle canvas system with natural DB query planning, visualization planning, revision history, share/fork, and client data lens.
- SGLang/OpenAI-compatible LLM runtime for coding/Oracle/NemoClaw workflows.
- ComfyUI/Dream Weaver image generation routed through Linux-origin and AWS GPU workers.
- Ingress-managed public routes under `velocity.desineuron.in`, `llm.desineuron.in`, and related Desineuron hostnames.

## 2. First Principles: What Problem Is This Solving?

### 2.1 Real Estate Sales Are Not Linear

A normal software CRM treats sales like a spreadsheet:

1. A lead enters.
2. Someone calls them.
3. The lead moves through stages.
4. Eventually the deal closes or dies.

Luxury real estate is messier:

- Multiple family members influence one purchase.
- WhatsApp is often more important than formal email.
- A client may show intent through a call, a site visit, a budget comment, a QD spike, or a property preference.
- The sales team needs to know not only "who is in the pipeline" but "who is emotionally and financially ready right now."
- Visual presentation matters because property is sold through imagination before it is sold through paperwork.

Velocity exists because a spreadsheet cannot hold that whole story.

### 2.2 The Core Data Truth

Velocity's most important asset is not the UI. It is the connected graph of:

- people
- leads
- properties
- opportunities
- property interests
- messages
- calls
- emails
- visits
- reminders
- QD scores
- extracted facts
- next-best actions
- generated canvases
- generated media

The UI is valuable only because it exposes this graph in usable form.

### 2.3 Why AI Is Used

AI is used for three jobs:

1. **Reasoning over data**
   - Example: "Which clients are interested in Atri Surya Toron but have low QD scores?"
   - The Oracle should translate the question into database access and return a visual answer.

2. **Perception and scoring**
   - Example: Sentinel interprets showroom engagement signals and turns them into QD-related intelligence.

3. **Media generation**
   - Example: Dream Weaver transforms a real room photograph into a staged interior render.

AI is not the product by itself. AI is the engine that helps the real-estate workflow move faster.

## 3. Current Repository Map

This is the practical map a new developer should use first.

| Path | Meaning | Notes |
| --- | --- | --- |
| `app/` | React WebOS frontend | Main operator interface. Uses Vite, React Router, Zustand, Tailwind, Framer Motion. |
| `app/src/App.tsx` | Frontend route shell | Defines module routes: Dashboard, Oracle, Sentinel, Inventory, Catalyst, CRM, Comms, Settings, Admin. |
| `app/src/components/layout/Sidebar.tsx` | WebOS navigation | Renders module icons and route links. |
| `app/src/components/modules/` | Main frontend module pages | Each major WebOS tab lives here or delegates into `app/src/app/*`. |
| `app/src/app/oracle/page.tsx` | Oracle WebOS page | Canvas, chat sessions, search, client data subtab, prompt bar, share/history controls. |
| `app/src/oracle/` | Oracle frontend components and API client | Canvas renderers, Client Data Lens, modals, hooks, and API calls. |
| `backend/main.py` | FastAPI entrypoint | Loads env, creates DB pool, applies migrations, mounts routers and WebSockets. |
| `backend/api/` | API router modules | Catalyst, CRM, Comms, Inventory, Oracle helper routes, admin, runtime LLM, etc. |
| `backend/routers/` | Legacy/specialized routers | Sentinel, CCTV, scenes, videos, vault. |
| `backend/auth/` | Login and JWT auth | User directory, `users_and_roles`, auth dependencies. |
| `backend/db/` | SQL schemas | Canonical CRM, comms, base schema, addenda. |
| `backend/oracle/` | Oracle backend brain | Natural DB agent, prompt orchestrator, canvas service, visualization planner, semantic catalog, plan verifier. |
| `backend/services/` | Shared service abstractions | Runtime LLM, NemoClaw, communications providers, ad network services. |
| `backend/scripts/seed_synthetic_crm.py` | Synthetic CRM loader | Defaults to `synthetic_crm_v2` when available. |
| `db assets/` | Seed data and inventory assets | Synthetic CRM v1/v2 CSV and JSON packs plus inventory files. |
| `comfy_engine/` | ComfyUI workflows and scripts | Dream Weaver, prompt expansion, queue/gateway helpers, media workflows. |
| `dw_gateway_v2_min.py` | Minimal Dream Weaver gateway | Public backend-facing async gateway that routes image generation jobs to Comfy workers. |
| `infrastructure/desineuron_ingress/` | Deployment and routing ops | Nginx/Caddy configs, route sync scripts, GPU worker pool services, SGLang scripts, watchdogs. |
| `iOS/` | Native iPad surface | Field app code and mobile experience work. |
| `android-edge-phone/`, `android-tablet/` | Android/mobile surfaces | Edge/mobile experiments and companion surfaces. |
| `.Agent Context/` | Working truth books and project docs | Planning, handoffs, runtime truth, testing reports. |

## 4. Runtime Architecture: The Mental Model

The easiest way to understand Velocity is to imagine three machines with three jobs.

### 4.1 Public Ingress

Ingress is the public front door. It terminates TLS and routes traffic.

Current relevant files:

- `infrastructure/desineuron_ingress/velocity.desineuron.in.nginx.conf`
- `infrastructure/desineuron_ingress/Caddyfile`
- `infrastructure/desineuron_ingress/api.desineuron.in.nginx.conf`
- route sync scripts under `infrastructure/desineuron_ingress/`

Responsibilities:

- Serve the WebOS static frontend.
- Proxy `/api/*` to the FastAPI backend.
- Proxy `/dream-weaver/*` to the Dream Weaver gateway.
- Proxy `/llm/*` or `llm.desineuron.in` to the LLM runtime path.
- Keep public routes stable even if backend/GPU private IPs change.

Analogy: Ingress is the receptionist. It does not do the work. It sends visitors to the right department.

### 4.2 Linux-Origin / Backend Box

Linux-origin is the control plane and main application backend.

Responsibilities:

- Run FastAPI backend.
- Serve or coordinate WebOS deployment.
- Own route-sync and orchestration scripts.
- Hold operational service files.
- Proxy/tunnel to GPU workers when direct routing is not appropriate.
- Run Dream Weaver gateway if configured there.

Analogy: Linux-origin is the operations manager. It coordinates the business, but it should not carry every heavy GPU workload.

### 4.3 GPU Box

The GPU box is the inference/media plane.

Responsibilities:

- Run SGLang for LLM inference when in LLM mode.
- Run ComfyUI workers for Dream Weaver when in media-generation mode.
- Keep models/checkpoints on NVMe.
- Avoid root disk model storage.

Analogy: The GPU box is the workshop. It does the heavy manufacturing.

## 5. Frontend Architecture

### 5.1 Main Frontend Stack

From `app/package.json`:

- React `19`
- Vite
- TypeScript
- React Router `7`
- Zustand
- Tailwind CSS
- Framer Motion
- Recharts
- MediaPipe Tasks Vision
- React Three Fiber / Drei
- Radix UI components

### 5.2 Route Shell

File:

- `app/src/App.tsx`

This file is the frontend root for the authenticated WebOS.

It defines `MODULE_ROUTES`:

| Module ID | Path | Title | Component |
| --- | --- | --- | --- |
| `dashboard` | `/dashboard` | Dashboard | `Dashboard` |
| `oracle` | `/oracle` | The Oracle | `Oracle` |
| `sentinel` | `/sentinel` | The Sentinel | `Sentinel` |
| `inventory` | `/inventory` | Inventory | `Inventory` |
| `catalyst` | `/catalyst` | The Catalyst | `Catalyst` |
| `crm` | `/crm` | CRM | `CRM` |
| `comms` | `/comms` | Conversations | `Comms` |
| `settings` | `/settings` | Settings | `Settings` |
| `admin` | `/admin` | Admin | `AdminPage` |

Important implementation detail:

- `RouteModuleSync` maps `location.pathname` into Zustand `activeModule`.
- `Sidebar` uses `NavLink` from React Router.
- The route-rendering region is keyed by `location.pathname`.
- Route rendering must remain synchronous. Heavy modules such as Oracle have async state, search overlays, history modals, and portals; route-level wait animations can leave stale Oracle content visible after navigation.

### 5.3 State Management

File:

- `app/src/store/useStore.ts`

The frontend uses Zustand for:

- auth state
- active module
- sidebar expansion
- Oracle legacy message state
- Sentinel visitor state
- dashboard metrics
- inventory state
- system status
- notifications

Only selected values are persisted in browser storage:

- `user`
- `activeModule`

Practical implication:

- A stale `activeModule` can affect labels or sidebar state, but the URL should be the real source of navigation truth.

### 5.4 Module Surfaces

| Module | Primary File | Purpose |
| --- | --- | --- |
| Dashboard | `app/src/components/modules/Dashboard.tsx` | Executive overview and system snapshot. |
| Oracle | `app/src/components/modules/Oracle.tsx` -> `app/src/app/oracle/page.tsx` | Natural DB canvas and CRM client lens. |
| Sentinel | `app/src/components/modules/Sentinel.tsx` | Live perception, biometric sessions, QD-oriented showroom intelligence. |
| Inventory | `app/src/components/modules/Inventory.tsx` | Property/project/unit browsing and media. |
| Catalyst | `app/src/components/modules/Catalyst.tsx` | Marketing and Dream Weaver surfaces. |
| Dream Weaver | `app/src/components/modules/CatalystDreamWeaverTab.tsx` | Image upload, room type, prompt keywords, async generated staging result. |
| CRM | `app/src/components/modules/CRM.tsx` | Canonical CRM operational surface. |
| Comms | `app/src/components/modules/Comms.tsx` | WhatsApp/conversation style messaging surface. |
| Settings | `app/src/components/modules/Settings.tsx` | Operator settings, integrations, configuration. |

## 6. Backend Architecture

### 6.1 Backend Entry Point

File:

- `backend/main.py`

Startup flow:

1. Load environment variables from:
   - explicit `VELOCITY_ENV_FILE`
   - `backend/.env`
   - repo `.env`
   - default dotenv behavior
2. Create asyncpg DB pool.
3. Apply migrations through `backend.migrations.runner.apply_migrations`.
4. Ensure user directory schema exists.
5. Mount routers.
6. Register WebSocket managers.
7. Serve `/health`.

Important backend routes are mounted in `backend/main.py`, not scattered through a framework convention. When onboarding, this file is the fastest way to see the backend surface area.

### 6.2 Router Mounts

| Router File | Prefix | Responsibility |
| --- | --- | --- |
| `backend/api/routes_catalyst.py` | `/api/catalyst` | Campaigns, creative sync, ad insights, budget/bid changes, audience sync. |
| `backend/api/routes_crm.py` | `/api`, `/api/analytics` | Legacy CRM and analytics routes. |
| `backend/api/routes_oracle.py` | `/api/oracle` | Oracle health, schema catalog, natural query, MCP/tools, actions. |
| `backend/oracle/router_v1.py` | `/api/oracle/v1` | Oracle canvas pages, prompts, forks, rollback, revisions, templates, merge requests, websocket. |
| `backend/api/routes_oracle_templates.py` | `/api/oracle` | Template chapters, subchapters, component templates, synthetic jobs. |
| `backend/routers/sentinel.py` | `/api/sentinel` | Sentinel websockets, consent, perception sessions, QD, lead tagging. |
| `backend/routers/cctv.py` | `/api/cctv` | CCTV event ingestion and auto-mode matching. |
| `backend/routers/scenes.py` | `/api/scenes` | Video scene map upload/list. |
| `backend/routers/videos.py` | `/api/videos` | Marketing video listing. |
| `backend/routers/vault.py` | `/api/vault` and `/vault` | Trackable asset links. |
| `backend/api/routes_mobile_edge.py` | `/api/mobile-edge` | iPad/mobile event, memory, calendar, import, transcripts, alerts, session heartbeat. |
| `backend/api/routes_inventory.py` | `/api/inventory` | Inventory import, property CRUD, property media. |
| `backend/api/routes_admin_surface.py` | `/api/admin-surface` | Admin health, queues, installs, actions, logs, template admin. |
| `backend/api/routes_observability.py` | `/api` | Request metrics. |
| `backend/api/routes_crm_imports.py` | `/api` | Canonical CRM contacts, client 360, opportunities, tasks, kanban, QD, client-data lens. |
| `backend/api/routes_comms.py` | `/api/comms` | Conversations, messages, provider settings, webhooks, transcription placeholder. |
| `backend/api/routes_runtime_llm.py` | `/api/runtime/llm` | Runtime LLM providers, chat, batch jobs. |
| `backend/auth/routes.py` | direct `/api/auth/*` | Login, current user, users, avatar upload. |

### 6.3 Authentication

Key files:

- `backend/auth/routes.py`
- `backend/auth/dependencies.py`
- `backend/auth/service.py`
- `backend/auth/user_directory.py`

Authentication is JWT-based.

Plain-English flow:

1. User enters email/password.
2. `/api/auth/login` checks `users_and_roles`.
3. Backend returns token.
4. Frontend stores token.
5. Future API calls send token.
6. Backend converts token into `UserPrincipal`.
7. Route handlers use `Depends(get_current_user)` when they need identity.

Important user-facing APIs:

- `POST /api/auth/login`
- `GET /api/auth/me`
- `GET /api/auth/users`
- `POST /api/auth/profile/avatar`

### 6.4 Static Assets

`backend/main.py` mounts `/assets` when `VELOCITY_ASSET_DIR` exists.

Default:

- `/opt/dlami/nvme/assets`

This matters for:

- profile avatars
- generated media
- vault assets
- communications media

## 7. Database And Data Model

### 7.1 The Database Is The Product Memory

Velocity's database is divided into domains:

| Domain | Prefix | Meaning |
| --- | --- | --- |
| CRM identity and pipeline | `crm_*` | People, accounts, leads, opportunities, interests, relationships, stage history. |
| Intelligence and interactions | `intel_*` | Messages, calls, visits, QD scores, transcripts, perception events, extracted facts. |
| Inventory | `inventory_*` | Projects and units. |
| Workflow | `workflow_*` | Actions, approvals, writebacks. |
| Oracle canvas | `oracle_*` | Canvas pages, revisions, components, templates, collaboration. |
| Comms | `comms_*` | Threads, messages, call logs, provider settings. |
| Legacy feeders | mixed | Older `leads`, `leads_intelligence`, `chat_logs`, `omnichannel_logs`, etc. |

### 7.2 Canonical CRM Schema

Primary schema file:

- `backend/db/schema_crm_canonical.sql`

Core tables include:

| Table | Meaning |
| --- | --- |
| `crm_people` | A person/contact. This is the anchor for client identity. |
| `crm_accounts` | Company, employer, broker, developer, referral partner, family account. |
| `crm_households` | Family/co-buyer grouping. |
| `crm_relationships` | Person-to-person relationship graph. |
| `crm_leads` | Sales funnel state for a person. |
| `crm_opportunities` | Deal pipeline object linked to lead/project/unit. |
| `crm_property_interests` | Which properties/projects/configurations a person has interest in. |
| `crm_stage_history` | Movement through stages over time. |
| `inventory_projects` | Real-estate projects. |
| `inventory_units` | Units/flats/inventory linked to projects. |
| `intel_interactions` | Unified interaction timeline events. |
| `intel_messages` | Message-level communication data. |
| `intel_calls` | Call metadata. |
| `intel_transcripts` | Call/transcript text. |
| `intel_emails` | Email interaction data. |
| `intel_visits` | Site visit data. |
| `intel_reminders` | Follow-up tasks/reminders. |
| `intel_qd_scores` | QD/intent/scoring events. |
| `intel_qd_timeseries` | QD score evolution. |
| `intel_extracted_facts` | Extracted facts like budget, objection, timeline, preference. |
| `intel_call_objections` | Objections raised during calls. |
| `read_last_contacted` | Read-model accelerator for last-contacted queries. |
| `read_next_best_action` | Read-model accelerator for next-action prompts. |

### 7.3 Synthetic CRM Dataset

Current default seed source:

- `db assets/synthetic_crm_v2/csv`

Legacy fallback:

- `db assets/synthetic_crm_v1/csv`

Loader:

- `backend/scripts/seed_synthetic_crm.py`

The loader defaults to v2 if present:

```python
_V2_CSV_DIR = REPO_ROOT / "db assets" / "synthetic_crm_v2" / "csv"
_V1_CSV_DIR = REPO_ROOT / "db assets" / "synthetic_crm_v1" / "csv"
CSV_DIR = _V2_CSV_DIR if _V2_CSV_DIR.exists() else _V1_CSV_DIR
```

Why this matters:

- Oracle and Client Data Lens are only as useful as the data loaded into the live DB.
- If the frontend shows "No data available", the first question is not "is the UI broken?" but "did the relevant DB table return rows?"
- The v2 pack is richer and includes read models and extracted intelligence that v1 did not fully cover.

### 7.4 Comms Schema

Primary schema file:

- `backend/db/schema_comms.sql`

Important tables:

| Table | Meaning |
| --- | --- |
| `comms_threads` | A WhatsApp/text conversation thread, optionally linked to `crm_people`. |
| `comms_messages` | Individual inbound/outbound/system messages. |
| `comms_call_logs` | Call records, recordings, transcript references. |
| `comms_settings` | Provider configuration for mock/WAHA/Evolution. |

Plain-English model:

- A phone number creates or maps to a thread.
- A thread can be linked to a CRM person.
- Messages and calls become part of the client story.
- Inbound provider webhooks can create CRM interactions when enabled.

## 8. Oracle: The Most Important Conceptual Module

### 8.1 What Oracle Is

Oracle is a canvas-based intelligence workspace.

It is not just a chatbot.

A chatbot produces text and forgets. Oracle produces persistent business artifacts:

- components
- tables
- charts
- timelines
- client summaries
- revision history
- share/fork flows
- merge review flows

### 8.2 Current Oracle Frontend

Important files:

- `app/src/app/oracle/page.tsx`
- `app/src/oracle/hooks/useOraclePage.ts`
- `app/src/oracle/hooks/useOracleExecution.ts`
- `app/src/oracle/lib/oracleApiClient.ts`
- `app/src/oracle/components/CanvasViewport.tsx`
- `app/src/oracle/components/ComponentRegistry.tsx`
- `app/src/oracle/components/ClientDataLens.tsx`
- `app/src/oracle/components/ShareModal.tsx`
- `app/src/oracle/components/RollbackConfirmModal.tsx`
- `app/src/oracle/components/renderers/*`

Current Oracle UI structure:

- Oracle Canvas subtab:
  - chat/canvas sidebar
  - New Chat
  - Search
  - recent canvas sessions
  - canvas viewport
  - prompt input
  - history/rail
  - share and rollback controls

- Client Data subtab:
  - client list
  - selected client record
  - editable details
  - property interests
  - engagement intelligence
  - extracted facts
  - timeline-style CRM lens

### 8.3 Current Oracle Backend

Important files:

- `backend/oracle/router_v1.py`
- `backend/oracle/prompt_orchestrator.py`
- `backend/oracle/natural_db_agent.py`
- `backend/oracle/semantic_catalog.py`
- `backend/oracle/plan_verifier.py`
- `backend/oracle/visualization_planner.py`
- `backend/oracle/canvas_service.py`
- `backend/oracle/collaboration_service.py`
- `backend/oracle/codebook_service.py`
- `backend/oracle/data_access_gateway.py`

### 8.4 Oracle Prompt Flow

Plain-English flow:

1. User enters a prompt in Oracle.
2. Frontend sends it to:
   - `POST /api/oracle/v1/canvas-pages/{page_id}/prompts`
3. Backend builds execution context.
4. Natural DB agent inspects schema/semantic catalog.
5. LLM/runtime service plans SQL.
6. Plan verifier checks the query.
7. SQL executes against the configured DB.
8. Result rows are analyzed.
9. Visualization planner selects component type.
10. Canvas service persists component plus `dataRows`.
11. Frontend refreshes and renders the component.

### 8.5 Oracle Natural DB Agent

File:

- `backend/oracle/natural_db_agent.py`

The agent pipeline is documented in its module docstring:

1. schema introspection
2. semantic SQL planning
3. plan verification and optional repair
4. SQL execution
5. execution quality profiling and auto-replan
6. visualization planning from actual result shape

Important implementation truth:

- The current code still includes SQL safety checks.
- Destructive SQL is blocked by pattern:
  - `insert`
  - `update`
  - `delete`
  - `drop`
  - `alter`
  - `truncate`
  - `copy`
  - `create`
  - `grant`
  - `revoke`
  - `call`
  - `execute`
  - `do`
  - `merge`

Why this exists:

- Oracle is intended to answer questions and build canvas artifacts.
- Writes are intended to go through typed APIs and explicit writeback actions.
- This prevents accidental mutation of production CRM data through an ambiguous natural-language prompt.

If a future architecture uses a true read/write sandbox copy, then destructive operations can be reconsidered there. In the current app DB path, read-first behavior is the defensible default.

### 8.6 Semantic Catalog

File:

- `backend/oracle/semantic_catalog.py`

Purpose:

- Give the planner a plain-language understanding of database tables and columns.
- Explain what columns mean, which values are valid, and how concepts map to the schema.

This solves a major LLM problem:

- A raw database schema tells the model column names.
- It does not tell the model business meaning.

Example:

- A column called `current_value` is ambiguous.
- A semantic catalog can say whether it is a QD score, monetary value, percentage, or scoring output.

This is similar to giving a new analyst both the spreadsheet and a glossary.

### 8.7 Visualization Planner

File:

- `backend/oracle/visualization_planner.py`

Purpose:

- Choose a canvas renderer from actual returned rows.

Examples:

| Result Shape | Likely Component |
| --- | --- |
| one numeric row | KPI tile |
| category + count | bar chart |
| timestamp + values | line chart |
| activity rows with timestamps | activity stream |
| stage-like data | pipeline board |
| general rows | table |

This layer is important because the LLM should not have to hand-code every UI layout. The backend can infer a good visualization based on data shape.

### 8.8 Known Oracle Failure Modes

| Symptom | Likely Cause | Where To Check |
| --- | --- | --- |
| Component appears but says no data | SQL returned zero rows, `dataRows` missing, or renderer received wrong binding | `natural_db_agent.py`, `canvas_service.py`, frontend renderer |
| Prompt returns too many rows | Planner ignored prompt limit or verifier did not enforce it | `natural_db_agent.py`, `plan_verifier.py` |
| Wrong score type used | Planner lacks semantic value guidance | `semantic_catalog.py`, `plan_verifier.py` |
| Recent-contact prompt returns stale/legacy data | Planner used sparse recency columns instead of interaction timeline/read model | `plan_verifier.py`, `semantic_catalog.py` |
| Canvas visible only after refresh | Frontend state/rendering issue | `app/src/App.tsx`, `app/src/app/oracle/page.tsx` |
| Share/fork appears to work but recipient cannot see useful rows | Components/revisions missing persisted `dataRows` | `canvas_service.py`, `schema_oracle.sql` |

## 9. Client Data Lens

The Client Data Lens is Oracle's operational CRM view.

Frontend:

- `app/src/oracle/components/ClientDataLens.tsx`

Backend:

- `backend/api/routes_crm_imports.py`

Key API endpoints:

- `GET /api/crm/client-data`
- `GET /api/crm/client-data/{person_id}`
- `PATCH /api/crm/client-data/{person_id}`
- `GET /api/crm/client-data/{person_id}/timeline`
- `POST /api/crm/client-data/{person_id}/tasks`

Purpose:

- Browse clients.
- Inspect one client's status, QD, last contact, next action, and details.
- Edit safe fields through typed APIs.
- See property interests and interaction signals.

Design principle:

- Oracle Canvas is exploratory and analytical.
- Client Data Lens is operational and record-oriented.

## 10. Comms / WhatsApp-Like Conversations

### 10.1 Purpose

Most real-estate communication happens over WhatsApp, calls, voice notes, and informal follow-ups. The Comms module is designed to make those interactions first-class CRM data.

Frontend:

- `app/src/components/modules/Comms.tsx`

Backend:

- `backend/api/routes_comms.py`

Services:

- `backend/services/comms_provider.py`
- `backend/services/comms_waha_provider.py`
- `backend/services/comms_evolution_provider.py`
- `backend/services/comms_ingest.py`

Schema:

- `backend/db/schema_comms.sql`

Supported provider modes:

- `mock`
- `waha`
- `evolution`

Important endpoints:

- `GET /api/comms/threads`
- `GET /api/comms/threads/{thread_id}`
- `GET /api/comms/threads/{thread_id}/messages`
- `POST /api/comms/threads/{thread_id}/messages`
- `POST /api/comms/threads/{thread_id}/link-person`
- `POST /api/comms/threads/{thread_id}/notes`
- `POST /api/comms/threads/{thread_id}/tasks`
- `POST /api/comms/webhooks/{provider}`
- `GET /api/comms/settings`
- `PATCH /api/comms/settings`
- `POST /api/comms/provider/test`
- `POST /api/comms/recordings/transcribe`

### 10.2 Comms Data Flow

Inbound WhatsApp-style flow:

1. Provider sends webhook.
2. `/api/comms/webhooks/{provider}` receives payload.
3. `comms_ingest.py` normalizes message.
4. Backend finds or creates `comms_threads`.
5. Backend inserts `comms_messages`.
6. If configured, thread auto-links to `crm_people` by phone.
7. If configured, inbound message creates CRM interaction.
8. Frontend Comms module displays the conversation.

Outbound flow:

1. User selects thread in WebOS.
2. User sends message.
3. Backend writes message and calls configured provider.
4. Provider returns external message ID/status.
5. Message remains tied to CRM person/thread.

## 11. Sentinel

Sentinel is the showroom perception module.

Backend:

- `backend/routers/sentinel.py`

Frontend:

- `app/src/components/modules/Sentinel.tsx`
- `app/src/components/modules/sentinel/*` when present

Core endpoints:

- `WebSocket /api/sentinel/ws/notifications`
- `WebSocket /api/sentinel/ws/perception`
- `POST /api/sentinel/consent`
- `POST /api/sentinel/session/complete`
- `POST /api/sentinel/tag-lead`
- `GET /api/sentinel/qd-score/{lead_id}`

Plain-English model:

- A showroom session can produce perception events.
- Those events inform QD and lead tagging.
- Consent is explicit and recorded.
- Browser-side MediaPipe means raw camera processing can stay closer to the client device.

## 12. Catalyst And Dream Weaver

### 12.1 Catalyst

Catalyst is the marketing and creative orchestration module.

Backend:

- `backend/api/routes_catalyst.py`

Frontend:

- `app/src/components/modules/Catalyst.tsx`
- `app/src/components/modules/CatalystDreamWeaverTab.tsx`
- `app/src/components/modules/CatalystMarketingTab.tsx`

Core responsibilities:

- campaign listing
- campaign creation
- creative sync
- ad insights
- budget updates
- bid strategy updates
- lookalike/custom audience sync
- Meta auth

### 12.2 Dream Weaver

Dream Weaver is a staging-image generation surface.

Key files:

- `dw_gateway_v2_min.py`
- `comfy_engine/scripts/prompt_expander.py`
- `comfy_engine/scripts/dw_gateway_v2.py`
- `app/src/components/modules/CatalystDreamWeaverTab.tsx`
- `app/src/lib/dreamWeaverApi.ts`
- `infrastructure/desineuron_ingress/comfyui-worker@.service`
- `infrastructure/desineuron_ingress/install_gpu_comfy_worker_pool.sh`
- `infrastructure/desineuron_ingress/install_linux_comfy_worker_tunnels.sh`
- `infrastructure/desineuron_ingress/hydrate_gpu_comfy_models.py`

Plain-English flow:

1. User uploads a room photo.
2. User selects room type and style keywords.
3. Frontend posts to `/dream-weaver`.
4. Gateway creates async job.
5. Gateway chooses a Comfy worker.
6. Image is uploaded to ComfyUI.
7. Prompt is expanded.
8. Workflow runs on GPU.
9. Frontend polls `/dream-weaver/status/{job_id}`.
10. When ready, frontend gets `/dream-weaver/result/{job_id}`.
11. User can view/download generated PNG.

Current important runtime truth:

- Dream Weaver can be configured to use a pool of Comfy workers, one per L4 GPU.
- `COMFYUI_URLS` controls the worker list.
- Long-running generation must use async polling, not one blocking request.
- Large upload support requires ingress body-size tuning.
- Models/checkpoints should be hydrated to GPU NVMe, not root disk.

## 13. Runtime LLM And SGLang

Backend:

- `backend/api/routes_runtime_llm.py`
- `backend/services/runtime_llm_service.py`
- `backend/services/nemoclaw_client.py`

Infrastructure:

- `infrastructure/desineuron_ingress/install_gpu_sglang_runtime.sh`
- `infrastructure/desineuron_ingress/install_gpu_sglang_watchdog.sh`
- `infrastructure/desineuron_ingress/sync_llm_route.py`

Current conceptual runtime:

- Public consumers should use OpenAI-compatible `/v1/*` where SGLang is active.
- `qwen3.6-35b-a3b` is the canonical SGLang model ID documented elsewhere in the runtime truth book.
- Ollama-era model IDs with colons are not appropriate for SGLang-facing clients.

Important operational caveat:

- A 4x L4 GPU box cannot always run every heavy workload at full size simultaneously.
- SGLang tensor-parallel LLM mode may consume all four GPUs.
- Dream Weaver 4-worker mode also wants all four GPUs.
- Operationally, this creates a mode-choice problem:
  - LLM-first mode
  - media-generation-first mode
  - or a smaller split profile

This should be documented and exposed as an operator decision rather than hidden.

## 14. Infrastructure And Deployment

### 14.1 Important Infrastructure Files

| File | Purpose |
| --- | --- |
| `infrastructure/desineuron_ingress/velocity.desineuron.in.nginx.conf` | Nginx public route config for main Velocity site. |
| `infrastructure/desineuron_ingress/api.desineuron.in.nginx.conf` | API hostname route config. |
| `infrastructure/desineuron_ingress/Caddyfile` | Caddy route/TLS config where used. |
| `infrastructure/desineuron_ingress/deploy_velocity_site.sh` | Deploy frontend/site artifacts. |
| `infrastructure/desineuron_ingress/install_linux_velocity_site_webhook.sh` | Linux deploy webhook service. |
| `infrastructure/desineuron_ingress/sync_velocity_route.py` | Sync Velocity route target. |
| `infrastructure/desineuron_ingress/sync_llm_route.py` | Sync LLM route target. |
| `infrastructure/desineuron_ingress/sync_comfy_route.py` | Sync Comfy route target. |
| `infrastructure/desineuron_ingress/sync_comfy_pool_routes.py` | Sync Comfy worker pool routing. |
| `infrastructure/desineuron_ingress/install_gpu_sglang_runtime.sh` | GPU SGLang runtime setup. |
| `infrastructure/desineuron_ingress/install_gpu_sglang_watchdog.sh` | GPU SGLang recovery. |
| `infrastructure/desineuron_ingress/install_gpu_comfy_worker_pool.sh` | Multi-GPU Comfy worker pool setup. |
| `infrastructure/desineuron_ingress/install_linux_comfy_worker_tunnels.sh` | Linux tunnels to GPU Comfy workers. |
| `infrastructure/desineuron_ingress/install_linux_dream_weaver_gateway.sh` | Dream Weaver gateway service setup. |
| `infrastructure/desineuron_ingress/hydrate_gpu_comfy_models.py` | Model/checkpoint hydration to GPU NVMe. |

### 14.2 Public Route Principles

Rules:

- Public users should not connect directly to GPU private/public IPs.
- Stable hostnames should hide backend movement.
- Ingress owns TLS and public contracts.
- Linux-origin coordinates target discovery.
- GPU worker owns inference/media runtime.

### 14.3 Why Route Sync Exists

Cloud private IPs can change when instances restart or are replaced. Hardcoding a GPU private IP in a public proxy creates a fragile system.

Route sync scripts solve this:

1. Discover current target instance/IP.
2. Render/update reverse proxy route.
3. Reload proxy.
4. Keep public route stable.

Analogy: The public phone number stays the same even if the office moves.

## 15. API Reference Corrections And Clarifications

The v1.1 API list is directionally useful, but a few details need correction:

1. Oracle v1 canvas routes currently use `canvas-pages`, not `/canvas/pages`.
   - Correct base: `/api/oracle/v1/canvas-pages`
   - Key prompt route: `/api/oracle/v1/canvas-pages/{page_id}/prompts`

2. Oracle v1 revision routes are:
   - `/api/oracle/v1/canvas-pages/{page_id}/revisions`
   - rollback is `/api/oracle/v1/canvas-pages/{page_id}/rollback`

3. Oracle sharing/fork route is:
   - `/api/oracle/v1/canvas-pages/{page_id}/forks`

4. Merge request routes are separate:
   - `/api/oracle/v1/merge-requests`
   - `/api/oracle/v1/merge-requests/{mr_id}/review`

5. Catalyst now includes more than the original list:
   - `GET /api/catalyst/campaigns`
   - `PUT /api/catalyst/budget`
   - `PUT /api/catalyst/bid-strategy`

6. Comms routes are now part of the product:
   - `/api/comms/*`

7. WebSocket routes include:
   - `/ws/catalyst`
   - `/ws/crm`
   - `/api/sentinel/ws/notifications`
   - `/api/sentinel/ws/perception`
   - `/api/oracle/v1/ws/oracle/canvas/{page_id}`

## 16. Onboarding Path For New Developers

### 16.1 If You Are Frontend-Focused

Read in this order:

1. `app/src/main.tsx`
2. `app/src/App.tsx`
3. `app/src/components/layout/Sidebar.tsx`
4. `app/src/store/useStore.ts`
5. the module you are changing under `app/src/components/modules/`
6. if Oracle-related:
   - `app/src/app/oracle/page.tsx`
   - `app/src/oracle/lib/oracleApiClient.ts`
   - `app/src/oracle/components/ComponentRegistry.tsx`
   - `app/src/oracle/components/renderers/*`

Mental model:

- App shell handles auth and routing.
- Sidebar changes URL.
- URL chooses module.
- Module calls backend API clients.
- Zustand stores global UI/auth state, not all business truth.

### 16.2 If You Are Backend-Focused

Read in this order:

1. `backend/main.py`
2. `backend/db/pool.py`
3. `backend/auth/routes.py`
4. `backend/auth/dependencies.py`
5. relevant router under `backend/api/` or `backend/routers/`
6. relevant service under `backend/services/`
7. relevant schema under `backend/db/`

Mental model:

- `main.py` mounts everything.
- Each router owns request/response shape.
- Services own provider/business logic.
- Database schema is explicit SQL.
- Auth is dependency-injected through FastAPI.

### 16.3 If You Are Oracle-Focused

Read in this order:

1. `app/src/app/oracle/page.tsx`
2. `app/src/oracle/lib/oracleApiClient.ts`
3. `backend/oracle/router_v1.py`
4. `backend/oracle/prompt_orchestrator.py`
5. `backend/oracle/natural_db_agent.py`
6. `backend/oracle/semantic_catalog.py`
7. `backend/oracle/plan_verifier.py`
8. `backend/oracle/visualization_planner.py`
9. `backend/oracle/canvas_service.py`
10. `backend/oracle/schema_oracle.sql`

Mental model:

- Prompt enters canvas route.
- Prompt becomes SQL/data plan.
- Rows become visualization decision.
- Components and rows persist.
- Frontend renders based on component type and `dataRows`.

### 16.4 If You Are Infrastructure-Focused

Read in this order:

1. `infrastructure/desineuron_ingress/README.md`
2. `infrastructure/desineuron_ingress/velocity.desineuron.in.nginx.conf`
3. route sync scripts:
   - `sync_velocity_route.py`
   - `sync_llm_route.py`
   - `sync_comfy_route.py`
   - `sync_comfy_pool_routes.py`
4. install scripts for the thing you are touching:
   - SGLang
   - Comfy
   - Dream Weaver gateway
   - site deploy webhook
5. related systemd service files

Mental model:

- Ingress is public contract.
- Linux-origin is control plane.
- GPU is compute plane.
- NVMe is model/media storage plane.

## 17. Common Debugging Playbooks

### 17.1 Frontend Page Does Not Change After URL Changes

Likely area:

- `app/src/App.tsx`
- React Router rendering
- route-level animation wrappers

Check:

- Does `location.pathname` change?
- Does Sidebar use `NavLink`?
- Is any route component kept mounted by `AnimatePresence mode="wait"`?
- Is a fixed overlay/portal covering the new page?

### 17.2 Login Fails With 502

Likely area:

- Ingress cannot reach FastAPI.
- Backend service is down.
- Backend failed startup due to DB/env/migration.

Check:

- public `/health`
- backend service logs
- nginx/caddy upstream config
- `DATABASE_URL` or DB pool startup

### 17.3 Oracle Shows Empty Components

Likely area:

- SQL returned zero rows.
- Component persisted without `dataRows`.
- Renderer expects different field names.
- Prompt planner selected wrong table or score type.

Check:

- `/api/oracle/query`
- `/api/oracle/data-health`
- `backend/oracle/natural_db_agent.py`
- `backend/oracle/visualization_planner.py`
- `backend/oracle/canvas_service.py`
- frontend renderer for that component type

### 17.4 Client Data Lens Shows No Clients

Likely area:

- CRM v2 seed data not loaded.
- Backend connected to wrong DB.
- `crm_people` empty.
- `/api/crm/client-data` returns empty.

Check:

- `backend/scripts/seed_synthetic_crm.py`
- `db assets/synthetic_crm_v2/csv`
- DB row counts
- backend env

### 17.5 Dream Weaver Upload Fails With 413

Meaning:

- Request body too large for ingress/proxy.

Check:

- `client_max_body_size` in nginx config.
- Caddy/nginx route config.
- Browser image size.

### 17.6 Dream Weaver Times Out

Likely area:

- Frontend polling too short.
- Gateway timeout too short.
- Comfy worker hung/errored.
- GPU out of memory.
- Checkpoint missing.

Check:

- `/dream-weaver/health`
- `/dream-weaver/status/{job_id}`
- Dream Weaver gateway logs
- Comfy worker logs
- GPU `nvidia-smi`
- checkpoint path on GPU NVMe

### 17.7 Comms Thread Does Not Link To Client

Likely area:

- Phone normalization mismatch.
- `autoLinkByPhone` disabled.
- `crm_people.primary_phone` not normalized.
- Provider webhook shape not mapped.

Check:

- `/api/comms/settings`
- `comms_ingest.py`
- `comms_threads.person_id`
- `crm_people.primary_phone`

## 18. Testing And Verification

### 18.1 Frontend

Primary build command:

```bash
cd app
npm run build
```

Development:

```bash
cd app
npm run dev
```

Local URL:

```text
http://127.0.0.1:5173/
```

### 18.2 Backend

Development command:

```bash
python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
```

Health:

```text
GET /health
```

### 18.3 Data Health

Oracle data health:

```text
GET /api/oracle/data-health
```

CRM smoke checks:

```text
GET /api/crm/client-data
GET /api/crm/contacts
GET /api/crm/opportunities
```

### 18.4 Dream Weaver Health

```text
GET /dream-weaver/health
POST /dream-weaver
GET /dream-weaver/status/{job_id}
GET /dream-weaver/result/{job_id}
```

### 18.5 Comms Health

```text
GET /api/comms/settings
GET /api/comms/threads
POST /api/comms/provider/test
```

## 19. Current Technical Debt And Risk Register

This section is intentionally direct. It helps new contributors avoid repeating known mistakes.

| Risk | Why It Matters | Recommended Direction |
| --- | --- | --- |
| Route/rendering coupling in WebOS | Heavy modules can leave stale UI if route transitions are too clever. | Keep route rendering synchronous and test navigation after Oracle/Catalyst changes. |
| Oracle prompt reliability | Natural-language SQL planning can be semantically wrong even when syntactically valid. | Improve semantic catalog, verifier, and result-quality profiler. |
| Data dependency | Oracle looks broken when DB seed/read models are missing. | Run data-health diagnostics before UI debugging. |
| GPU mode contention | SGLang TP=4 and Comfy 4-worker pool both want all L4 GPUs. | Make operator mode explicit: LLM mode vs Dream Weaver pool mode vs split mode. |
| Ingress timeouts/body limits | Media uploads and generation jobs need different limits than normal API calls. | Keep Dream Weaver async and tune route-specific limits. |
| Generated assets/storage | Media should not live on root disk. | Use NVMe/S3-backed asset paths consistently. |
| Comms provider abstraction | WAHA/Evolution/mock modes can diverge in payload shape. | Keep provider-normalized internal message model stable. |
| API documentation drift | Routes move faster than docs. | Generate or audit route list from `@router` declarations during releases. |
| Synthetic data realism | Demo quality depends heavily on realistic conversations, transcripts, objections, and follow-ups. | Continue enriching v2 data rather than creating disconnected datasets. |

## 20. Glossary For Non-Technical Stakeholders

| Term | Plain Meaning |
| --- | --- |
| API | A doorway through which the frontend asks the backend to do something. |
| Backend | The server-side brain of the product. |
| Canvas | A persistent workspace of generated Oracle insights. |
| Component | One visual block on a canvas, such as a chart or table. |
| ComfyUI | The image-generation engine used by Dream Weaver. |
| DB / Database | The system memory. |
| FastAPI | The Python framework used for the backend. |
| Frontend | The user interface people click and see. |
| GPU | Hardware used for heavy AI/image generation. |
| Ingress | The public routing layer that receives internet traffic. |
| LLM | A language model used for reasoning or prompt expansion. |
| NVMe | Fast local disk used for models and media. |
| Oracle | The natural-language analytics and canvas system. |
| QD Score | Velocity's scoring signal for qualification/desire/intent. |
| Router | Backend file that defines API endpoints. |
| SGLang | High-performance LLM serving runtime. |
| Tenant | A customer/company boundary. |
| WebSocket | A live connection for real-time updates. |

## 21. The One-Page Mental Model

If you remember only one thing, remember this:

Velocity is a private real-estate intelligence OS.

The frontend is the cockpit.  
The backend is the control tower.  
The database is the memory.  
Oracle turns memory into answers.  
Sentinel turns showroom signals into intent.  
Comms turns conversations into CRM intelligence.  
Catalyst and Dream Weaver turn property material into persuasive media.  
Ingress keeps the public contract stable.  
The GPU box performs the heavy AI work.  

Everything valuable in the system should eventually connect back to a client, a property, an interaction, an action, or a generated artifact.

That is the core truth of Project Velocity.

## 22. Oracle Canvas Execution Modes And Colony Routing

This section records the May 3, 2026 integration direction for bringing Sourik's Colony orchestration into Sayan/Sagnik's root architecture without breaking Oracle Canvas.

Oracle Canvas remains the single user-facing workspace. The frontend does not call Colony directly. Instead, the Oracle prompt endpoint accepts an execution mode and the backend chooses the execution engine.

### 22.1 User-Facing Modes

| Mode | User Meaning | Backend Behavior |
| --- | --- | --- |
| `auto` | Let Velocity choose. | Backend classifies prompt complexity. Simple prompts run through Oracle; complex/multi-round prompts dispatch to Colony. |
| `fast` | Prioritize direct canvas response. | Force existing Oracle prompt orchestrator. Best for tables, summaries, charts, and single-step canvas edits. |
| `thinking` | Use deeper multi-agent reasoning. | Force Colony mission dispatch. Best for CRM + Oracle + Catalyst tasks, multi-round analysis, writeback proposals, and cross-module strategy. |

### 22.2 Safe Integration Rule

Colony must not directly mutate CRM, Oracle, Catalyst, or inventory records from the first pass. Colony should produce artifacts and writeback proposals. Human approval remains explicit through root APIs.

This keeps production safety clear:

```text
Colony can recommend.
Root stores the recommendation.
Oracle Canvas shows it.
The operator approves or rejects it.
Only approved writebacks should touch business data.
```

### 22.3 Routing Diagram

```mermaid
flowchart TD
    U[Operator in Oracle Canvas] --> UI[Prompt bar mode: auto / fast / thinking]
    UI --> API[POST /api/oracle/v1/canvas-pages/{page_id}/prompts]

    API --> M{executionMode}
    M -->|fast| O[Oracle prompt_orchestrator]
    M -->|thinking| C[Colony mission dispatch]
    M -->|auto| H{Backend complexity heuristic}

    H -->|simple| O
    H -->|complex or multi-round| C

    O --> OC[Commit Oracle canvas components]
    C --> DB[(PostgreSQL colony_missions)]
    C --> GW[COLONY_SERVICE_URL /missions]
    GW --> WORKERS[Colony specialist workers]
    WORKERS --> ART[Tasks, results, writeback proposals]
    ART --> DB

    DB --> STATUS[Oracle canvas status component]
    STATUS --> OC

    OC --> REVIEW[Operator reviews artifacts/proposals]
    REVIEW --> APPROVE[Approve or reject writebacks]
    APPROVE --> ROOT[Root CRM / Oracle / Catalyst write APIs]
```

### 22.4 Current Implementation Notes

The first integration keeps the public Oracle prompt endpoint stable and extends the payload with:

```json
{
  "executionMode": "auto"
}
```

The frontend exposes this as a segmented control beside the Oracle prompt actions. The backend resolves the final route:

```text
auto      -> heuristic decides fast or thinking
fast      -> Oracle prompt_orchestrator
thinking  -> ColonyRepository + ColonyGateway
```

If Colony is selected but `COLONY_SERVICE_URL` is missing or unreachable, the backend returns an explicit production error instead of falling back to fake data.