sayan/Project_Velocity
1
1
Fork 0
forked from sagnik/Project_Velocity
Code Issues Pull Requests Activity
Files
eeb684b46c33a9709897aa4226878913cad9a258
Project_Velocity/.Agent Context/Codebase Analysis Docs/Codebase Analysis v1.2.md
sayan eeb684b46c feat: Ipad app production readiness, Colony orchestration, Social posting (#44) 
#38 Ipad app production readiness, Colony orchestration, Social posting

Co-authored-by: Sayan Datta <sayan@Sayans-MacBook-Air.local>
Reviewed-on: sagnik/Project_Velocity#44
2026-05-03 18:30:38 +05:30

82 KiB
Raw Blame History

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

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

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

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:

_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:

cd app
npm run build

Development:

cd app
npm run dev

Local URL:

http://127.0.0.1:5173/

18.2 Backend

Development command:

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

Health:

GET /health

18.3 Data Health

Oracle data health:

GET /api/oracle/data-health

CRM smoke checks:

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

18.4 Dream Weaver Health

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

18.5 Comms Health

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:

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

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:

{
  "executionMode": "auto"
}

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

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.

Reference in New Issue View Git Blame Copy Permalink