Velocity-OS/.agent context/Get Started/Codebase Analysis/Codebase Analysis v1.0.md

Codebase Analysis v1.0.md

Table of Contents / Chapters

1. Overview

• Introduction to Velocity-OS
• Core principles and containerized 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 (K3s, AWS ECR, MIG)

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
• Sentinel Biometric Intelligence Endpoints
• Catalyst Marketing Orchestration Endpoints
• Vault Trackable Links Endpoints
• CCTV Surveillance Integration Endpoints
• Mobile Edge Communication Endpoints
• Inventory Management Endpoints
• Infrastructure Notes

Overview

Velocity-OS is the production-grade evolution of Project Velocity. It is an on-prem real estate operating system designed for high-value property sales, deployed as a secure, containerized K3s appliance. It combines a premium WebOS (React 19, Vite, Three.js), an iPad field app, a FastAPI neural core, ComfyUI-based media generation, and biometric/sentiment-assisted sales intelligence.

Unlike its monolithic predecessor, Velocity-OS enforces strict infrastructure-as-code principles, utilizing AWS ECR for immutable artifacts, Traefik for ingress routing, and K3s with NVIDIA MIG (Multi-Instance GPU) for absolute performance isolation.

Architectural Mapping

Overall System Architecture

graph TB
    subgraph "User Interfaces"
        WebOS[Velocity WebOS<br/>React 19 + Vite + R3F]
        iPad[iPad App<br/>Swift + MediaPipe]
    end
    
    subgraph "K3s Cluster (On-Prem / Cloud)"
        Traefik[Traefik Ingress Controller]
        
        subgraph "Velocity-OS Pods"
            FastAPI[FastAPI Core<br/>API + WS]
            WebFront[Nginx Frontend<br/>Static Assets]
            ComfyEngine[Media Engine<br/>ComfyUI]
            DB[(PostgreSQL<br/>StatefulSet)]
            Redis[(Redis Cache)]
        end
    end
    
    subgraph "AI Services"
        Oracle[The Oracle<br/>Natural Language]
        Sentinel[The Sentinel<br/>Biometric]
        Catalyst[The Catalyst<br/>Marketing]
    end
    
    WebOS --> Traefik
    iPad --> Traefik
    Traefik --> FastAPI
    Traefik --> WebFront
    FastAPI --> Oracle
    FastAPI --> Sentinel
    FastAPI --> Catalyst
    Catalyst --> ComfyEngine
    FastAPI --> DB
    
    style FastAPI fill:#e1f5fe
    style Oracle fill:#f3e5f5
    style Sentinel fill:#e8f5e8
    style Catalyst fill:#fff3e0

Data Flow Architecture

flowchart LR
    User[User Input] --> UI[WebOS UI]
    UI --> API[FastAPI Endpoints]
    API --> Auth[JWT Authentication]
    API --> Policy[Policy Engine<br/>Authorization]
    API --> LLM[Nemoclaw LLM]
    LLM --> Query[SQL Generation]
    Query --> DB[(PostgreSQL)]
    DB --> Results[Query Results]
    Results --> Viz[Visualization]
    Viz --> Canvas[Oracle Canvas]
    Canvas --> UI
    
    Sentinel[Sentinel Biometric] --> WS[WebSocket<br/>Real-time]
    WS --> Perception[Face Analysis]
    Perception --> QD[QD Scoring]
    QD --> DB
    
    style DB fill:#fff9c4
    style LLM fill:#e8f5e8

Logic Decomposition

Infrastructure & Deployment (K3s, AWS ECR, MIG)

What: Production-ready containerized orchestration. How: K3s running on local NVMe storage, with NVIDIA MIG partitioning a single high-end GPU (e.g. RTX 6000 Ada with 48GB/48GB slices) to run LLMs and ComfyUI concurrently. Why: Real estate firms demand data sovereignty, zero-latency inference, and extreme reliability.

Key Components:

• K3s Manifests: Declarative state for Postgres, Redis, Core API, and WebOS.
• MIG GPU Slices: Physical isolation of VRAM guarantees ComfyUI generation never stutters the LLM conversational reasoning.
• AWS ECR: Private, secure registry for holding version-locked artifacts of Velocity-OS.
• Air-Gapped Polling: The system pulls updates via poll_and_transfer.sh ensuring the local Linux box maintains a strong security perimeter.

Connectivity Matrix

Component	Inputs	Outputs	Dependencies	Protocols
WebOS Frontend	User actions	UI renders	FastAPI backend	HTTP/WS, JWT
FastAPI Core	API requests, WS	DB queries, AI	PostgreSQL, Redis	SQL, HTTP
Oracle Engine	Natural language	Canvas	NemoClaw LLM	Internal API
Sentinel Engine	Webcam streams	QD scores	MediaPipe	WS real-time
K3s Traefik	External Traffic	Pod Routing	SSL Certs	HTTPS/WSS

First-Principles Guide

Velocity-OS operates on the principle that human sales professionals excel at relationship-building, while AI excels at pattern recognition. The system amplifies their capabilities by providing real-time insights securely.

Principle 1: Data Sovereignty First

Velocity-OS runs as a K3s appliance on-premise or in tenant-controlled environments.

Principle 2: Real-Time Perception Matters

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

Principle 3: Intelligence Through Conversation

The Oracle translates natural language into structured analytics, generating safe SQL queries.

Principle 4: Visual Storytelling Drives Sales

ComfyUI workflows create property visualizations locally without cloud dependency latency.

API Endpoints Reference

The endpoints are identical to Project Velocity, securely proxied by Traefik. For a full list, refer to the original Project_Velocity codebase analysis. Key highlights:

• POST /api/auth/login
• GET /api/oracle/schema-catalog
• POST /api/oracle/mcp/execute
• wss://<host>/api/sentinel/ws/notifications
• POST /api/catalyst/campaigns/create

---

Generated by Velocity-OS Setup sequence