Data & Docs: Add synthetic DB seed script and Codebase Analysis

.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<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*

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;