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

```mermaid
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

```mermaid
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*