Project_Velocity/.Agent Context/Codebase Analysis v1.1.md

Codebase Analysis v1.1.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