diff --git a/.agent context/Get Started/Codebase Analysis/Codebase Analysis v1.0.md b/.agent context/Get Started/Codebase Analysis/Codebase Analysis v1.0.md new file mode 100644 index 0000000..50356f2 --- /dev/null +++ b/.agent context/Get Started/Codebase Analysis/Codebase Analysis v1.0.md @@ -0,0 +1,177 @@ +# 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
React 19 + Vite + R3F] + iPad[iPad App
Swift + MediaPipe] + end + + subgraph "K3s Cluster (On-Prem / Cloud)" + Traefik[Traefik Ingress Controller] + + subgraph "Velocity-OS Pods" + FastAPI[FastAPI Core
API + WS] + WebFront[Nginx Frontend
Static Assets] + ComfyEngine[Media Engine
ComfyUI] + DB[(PostgreSQL
StatefulSet)] + Redis[(Redis Cache)] + end + end + + subgraph "AI Services" + Oracle[The Oracle
Natural Language] + Sentinel[The Sentinel
Biometric] + Catalyst[The Catalyst
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
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
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:///api/sentinel/ws/notifications` +- `POST /api/catalyst/campaigns/create` + +--- +*Generated by Velocity-OS Setup sequence* diff --git a/core/db/seed_test_users.sql b/core/db/seed_test_users.sql new file mode 100644 index 0000000..96bad06 --- /dev/null +++ b/core/db/seed_test_users.sql @@ -0,0 +1,88 @@ +-- ================================================================ +-- Velocity-OS Test Users Seed (FOR TESTING ONLY — NOT FOR PROD) +-- ================================================================ +-- Generated by seed_test_users.py + +BEGIN; + +-- Sagnik Ghosh (ADMIN) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('sagnik@desineuron.in', '$2b$12$k.gvWz2vu4mktqoIgskWrOie.lhsK1d0lT.3l/21Yb7SP0UQAX8n6', 'ADMIN', 'tenant_velocity', 'Sagnik Ghosh', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +-- Sayan Ghosh (SALES_DIRECTOR) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('sayan@desineuron.in', '$2b$12$viv3D0mWaPj5m5L9uhiauedFFyhA0bfkQGnN1ueEvpMarFs.GV7tG', 'SALES_DIRECTOR', 'tenant_velocity', 'Sayan Ghosh', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +-- Sourik Ghosh (SENIOR_BROKER) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('sourik@desineuron.in', '$2b$12$Hta1pa1E1C5g5rDOU/SyregtTxUaT34H6Rt.4SnC1jOQtWFZOp4MC', 'SENIOR_BROKER', 'tenant_velocity', 'Sourik Ghosh', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +-- Abantika Das (SENIOR_BROKER) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('abantika@desineuron.in', '$2b$12$aTADkh.1qBKH/htHkehafOIzXZfvfyG5zp19zxSllGg3JOfaBsqPe', 'SENIOR_BROKER', 'tenant_velocity', 'Abantika Das', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +-- Sinjini Roy (JUNIOR_BROKER) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('sinjini@desineuron.in', '$2b$12$WNqPTLPOidK6cyVC6wZsv.U6uHdS9RLOd5tA0jG13zzXs3v1UqT4W', 'JUNIOR_BROKER', 'tenant_velocity', 'Sinjini Roy', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +-- Swastika Ghosh (JUNIOR_BROKER) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('swastika@desineuron.in', '$2b$12$mDjbHxMFJuhKwbmwP.RxGeFw3iu.PQtfI.v.9S6coJLd95hotlaRS', 'JUNIOR_BROKER', 'tenant_velocity', 'Swastika Ghosh', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +-- Debargha Mukherjee (JUNIOR_BROKER) +INSERT INTO users_and_roles + (email, password_hash, role, tenant_id, full_name, is_active) +VALUES + ('debargha@desineuron.in', '$2b$12$7lKw441xRWxmLV9g7d1I7enOTcLsfrymE281jvYsYybCKsqZaSAy2', 'JUNIOR_BROKER', 'tenant_velocity', 'Debargha Mukherjee', TRUE) +ON CONFLICT (email) DO UPDATE + SET password_hash = EXCLUDED.password_hash, + role = EXCLUDED.role, + full_name = EXCLUDED.full_name, + is_active = TRUE; + +COMMIT; + +-- Verify: +SELECT email, role, full_name FROM users_and_roles ORDER BY role DESC, email; \ No newline at end of file