Project_Velocity/.Agent Context/Bibels/Project Velocity Master Bibel.md

# Project Velocity Master Bibel

**Status:** Master source of truth  
**Prepared:** 2026-04-12  
**Scope:** Unified synthesis of Project Velocity markdown documentation across product, architecture, infrastructure, operations, iOS, web, AI workflows, and GTM context  
**Exclusions:** Anything under `Sourik` was intentionally excluded from this synthesis  
**Method:** This document normalizes and reconciles the current documentation corpus. It is not a raw concatenation. Where source docs disagree, this bibel favors the latest operational truth and the more concrete implementation artifact.

---

## Chapter Index

1. Charter and Scope
2. Source Corpus
3. Product Thesis
4. Commercial Model
5. Customer and User Model
6. Suite Architecture
7. Core Product Surfaces
8. Oracle
9. Sentinel
10. Dream Weaver and Catalyst
11. Web Application
12. iOS Application
13. Backend and AI Runtime
14. Data Model and Core Entities
15. Infrastructure and Deployment Model
16. Stable Ingress Layer
17. Linux AWS Control Surface
18. Operating Flows
19. Security, Privacy, and Sovereignty
20. Current Live Truth
21. Build Priorities and Open Gaps
22. Runbooks and Team Usage
23. Source Lineage Map

---

## 1. Charter and Scope

Project Velocity is not one app. It is a private, on-prem or client-controlled real-estate operating system composed of:

- a premium web interface
- a native iPad surface
- an AI CRM and analytics layer
- a biometric perception and scoring layer
- a visual generation layer
- a durable infrastructure and operator layer

Velocity is designed around an anti-SaaS principle:

- client data stays with the client
- deployments can run on-prem or in client-controlled cloud
- the product is sold as strategic capability, not seat-based software

This master bibel exists to collapse scattered markdown artifacts into one normalized document the team can use as the primary reference.

---

## 2. Source Corpus

This bibel synthesizes the key Project Velocity markdown sources, including:

- core bibles:
  - `velocity_technical_bible.md`
  - `velocity_ios_bible.md`
  - `Project Velocity - The Oracle.md`
  - `The Sentinel Bibel.md`
  - `Desineuron Ops Control Plane Bibel.md`
- infrastructure:
  - `TEAM_HANDOFF_2026-04-08.md`
  - ingress and ops control plane READMEs
- Comfy and Dream Weaver:
  - `DREAMWEAVER_TECHNICAL_SPEC.md`
  - `A100_DEPLOYMENT_VALIDATION.md`
  - `comfy_engine/scripts/README.md`
- operational truth docs:
  - `nemoclaw_setup_truth.md`
  - `velocity_status_report.md`
  - `oracle_development_status.md`
- strategic and customer docs:
  - Kolkata builder intel
  - Customer 0 strategy
  - customer persona notes
  - sprint and user story docs

Excluded from synthesis:

- any path containing `Sourik`
- vendor or dependency markdown such as `node_modules`
- non-authoritative third-party readmes unless they directly influenced repo behavior

---

## 3. Product Thesis

Velocity is a real-estate sales acceleration platform for high-value property selling environments.

Its core promise is:

- compress sales cycles
- increase intelligence during sales interactions
- reduce lead leakage
- preserve data sovereignty
- give each property or portfolio a private, premium operating stack

The product is built around a first-principles model:

- property-specific intelligence matters
- portfolio intelligence unlocks when multiple properties are active
- AI should operate the workflow surface, not just answer questions
- product delivery must be standardized enough to avoid bespoke installation chaos

Velocity is therefore best understood as a modular operating system, not a single dashboard.

---

## 4. Commercial Model

The business model reflected in the documentation is:

- initial setup fee
- monthly maintenance / bleeding-edge upgrade fee
- inventory-linked or performance-linked downstream value capture

The product is not sold primarily by seats. The most important commercial unit is the property, with portfolio behavior unlocking when multiple properties are onboarded.

Working internal segmentation:

- **Tier 3 / city-channel model**
  - CP or channel-heavy deployment
  - one city per install
  - can cover many builders in that city
  - user count can still be high
- **Tier 2 / project-builder model**
  - per-project deployment for a builder
  - narrower operational scope
  - property-specific generation and sales workflows
- **Tier 1 / enterprise portfolio model**
  - multi-property or multi-portfolio controls
  - monitoring and interaction layers across properties
  - governance and deeper integrations

Commercially, the strongest internal framing is:

- first property gets full setup
- second property unlocks portfolio features
- enterprise control grows with property count and operational complexity

---

## 5. Customer and User Model

### Customer Types

- developers / builders
- brokerages and CPs
- city-channel sales operators
- enterprise portfolio operators

### Internal User Types

- junior broker
- senior broker
- sales director
- marketing operator
- data steward
- compliance reviewer
- platform admin
- operator / infra admin

### Team Reality

The current docs imply two simultaneous realities:

- product reality for future customers
- internal Desineuron operating reality used to build, demo, and run the system

This bibel captures both, but prefers the operational truth when implementation details matter.

---

## 6. Suite Architecture

```mermaid
flowchart TD
    A[Velocity User Surface] --> B[Web App]
    A --> C[iPad App]
    B --> D[FastAPI Neural Core]
    C --> D
    D --> E[Oracle]
    D --> F[Sentinel]
    D --> G[Inventory]
    D --> H[Dream Weaver / Catalyst]
    E --> I[PostgreSQL]
    F --> I
    G --> I
    D --> J[NemoClaw / Reasoning Layer]
    H --> K[ComfyUI / GPU Workloads]
    L[Linux Control Surface] --> M[AWS GPU Nodes]
    L --> N[S3 Canonical Asset Store]
    O[t4g Stable Ingress] --> B
    O --> C
    O --> L
    O --> M
```

Velocity has four major planes:

- **experience plane**
  - web app
  - iPad app
- **intelligence plane**
  - Oracle
  - Sentinel
  - NemoClaw
  - Dream Weaver / Catalyst
- **data plane**
  - PostgreSQL
  - asset storage
  - S3 model store
- **operations plane**
  - Linux control surface
  - stable ingress
  - AWS GPU workers

---

## 7. Core Product Surfaces

The currently documented product surfaces are:

- **Dashboard**
  - KPIs, health, activity, sentiment, velocity
- **Oracle**
  - AI CRM and analytical canvas
- **Sentinel**
  - biometric and attention-scoring engine
- **Inventory**
  - unit and property availability tracking
- **Dream Weaver / Catalyst**
  - visual generation and asset transformation
- **Settings / operator surfaces**
  - system configuration, connectivity, route control, infra control

---

## 8. Oracle

Oracle is the AI operating surface of Velocity. It is not a simple chatbot.

### What Oracle Is

- a prompt-driven CRM intelligence surface
- a persistent vertical canvas
- a branchable and mergeable analytical workspace
- a controlled data access gateway mediated by Nemoclaw and policy

### Core Oracle Principles

- natural-language intent becomes typed execution
- durable page revisions replace ephemeral AI replies
- collaboration uses forks and merge requests
- provenance and auditability are mandatory
- AI planning must remain policy-constrained

### Oracle Architecture

```mermaid
flowchart LR
    A[User Prompt] --> B[Prompt Execution]
    B --> C[NemoClaw Planning]
    C --> D[Policy Validation]
    D --> E[Data Access Gateway]
    E --> F[PostgreSQL / Tenant Data]
    F --> G[Visualization Resolver]
    G --> H[Canvas Component]
    H --> I[Revisioned Oracle Canvas]
    I --> J[Fork / Merge Workflow]
```

### Core Oracle Behaviors

- prompt authoring with context
- retrieval planning through semantic mapping
- policy-validated data access
- component synthesis or template selection
- append/insert/replace on a vertically scrolling canvas
- fork and merge semantics for shared work

### Oracle Truth in Repo

The repo has:

- a styled Oracle shell
- temporary mock-oriented UI behavior
- placeholder backend Oracle route files

The repo does not yet have:

- the full production Oracle runtime mounted and wired end to end

So Oracle is conceptually mature, but partially implemented.

---

## 9. Sentinel

Sentinel is the biometric, session-intelligence, and attention-scoring engine.

### Core Principles

- local-first perception
- no raw webcam stream to remote backend
- PostgreSQL as source of truth
- real-time broker-facing intelligence
- infrastructure truth over nostalgic planning

### Sentinel Inputs

- browser-side facial blendshape data
- scene timing
- CRM context
- asset opens
- CCTV enrichment
- auto-mode session evidence

### Sentinel Outputs

- QD score
- lead tags
- live notifications
- session intelligence
- vault-open intelligence
- auto-mode lead linkage

### Sentinel Modes

- **Assigned Mode**
  - tied to existing lead
- **Auto Mode**
  - no pre-bound lead
  - CCTV and session evidence reconcile later

### Sentinel Flow

```mermaid
flowchart TD
    A[Browser Webcam + MediaPipe] --> B[Biometric Packets]
    B --> C[/api/sentinel/ws/perception]
    C --> D[Scene Lookup]
    D --> E[NemoClaw Scoring]
    E --> F[perception_sessions]
    E --> G[omnichannel_logs]
    E --> H[Live QD Broadcast]
    I[CCTV OCR/Event] --> J[/api/cctv/event]
    J --> K[Auto Mode Matcher]
    K --> L[Lead Link or Lead Create]
```

### Active Truth

The docs are explicit that:

- NVIDIA-hosted completions are the active primary path
- Ollama/OpenShell exist but are not the production-first scoring path

That distinction should remain explicit in team communication.

---

## 10. Dream Weaver and Catalyst

Dream Weaver is the structural-preservation visual restyling system. Catalyst is the broader generation and asset automation layer.

### Dream Weaver Objective

Restyle interiors while preserving:

- geometry
- window placement
- vanishing points
- architectural truth

### Technical Strategy

- RealVisXL V5.0 Lightning as core model family in the historical design docs
- stacked ControlNet approach
- depth + line preservation
- SAM-based masking
- workflow portability through ComfyUI API JSON

### Operational Direction

The later infra work also shows Qwen-based image edit/generation workflows entering the stack. So the project now contains two overlapping visual-generation realities:

- Dream Weaver spec centered on SDXL / RealVisXL / ControlNet / SAM
- operational AWS generation work centered on Qwen image models and ComfyUI / GPU orchestration

These should be treated as parallel capabilities, not contradictions.

### Dream Weaver Pipeline

```mermaid
flowchart LR
    A[Reference / Room Image] --> B[Preprocess]
    B --> C[M-LSD]
    B --> D[Depth]
    B --> E[SAM / Masking]
    C --> F[Control Stack]
    D --> F
    E --> F
    F --> G[Sampler / Restyler]
    G --> H[Styled Output]
    H --> I[API / iPad / Batch Workflow]
```

### Operational Purpose

- interior restyling
- marketing posters
- cinematic video
- mobile-triggered asset generation
- broker-facing wow factor

---

## 11. Web Application

The web app is a React + TypeScript + Vite application.

### Frontend Stack

- React 19
- TypeScript
- Vite
- Zustand
- Tailwind CSS
- shadcn/ui
- Radix UI
- Framer Motion
- Recharts
- React Hook Form
- Zod

### Core Web Modules

- Dashboard
- Oracle
- Sentinel
- Inventory
- Settings

### State Model

The docs describe Zustand-backed state slices for:

- auth
- navigation
- Oracle
- Sentinel
- Dashboard
- Inventory
- system state

### Current Truth

The web app appears stronger as a polished shell than as a fully integrated production data surface. It carries much of the premium experience language and component structure the rest of the system is meant to converge toward.

---

## 12. iOS Application

Velocity iOS is the native mobile counterpart for Apple devices, especially the showroom iPad surface.

### iOS Stack

- Swift
- SwiftUI
- Combine / Observation
- Alamofire for networking
- native animation and glassmorphism

### iOS Modules

- Dashboard
- Oracle
- Sentinel
- Inventory
- Settings

### Strategic Role

The iPad app is not just a companion. It is central to the product’s premium physical-sales-gallery positioning.

Important documented capabilities:

- portable sales intelligence
- native presentation surface
- AI generation triggering
- AR sun-path overlay
- inventory and lead interaction on the floor

### Design Direction

- native fluidity
- battery efficiency
- premium dark/glass aesthetic
- parity with web where needed, but not web-in-a-wrapper

---

## 13. Backend and AI Runtime

The backend is a FastAPI neural core with PostgreSQL, auth, websockets, and AI orchestration.

### Key Responsibilities

- API routing
- auth and RBAC
- CRM and lead operations
- Sentinel perception processing
- Oracle execution path
- websockets and notifications
- video and scene catalog access
- NemoClaw integration

### NemoClaw Role

NemoClaw is the reasoning layer used across:

- lead tagging
- CCTV profiling
- QD scoring
- future Oracle planning and data access interpretation

### Prompt Truth in Repo

The repo contains explicit prompt artifacts for:

- `cctv_profiler`
- `lead_tagger`
- `qd_calculator`

These are concrete prompt contracts, not vague intentions. They should be treated as product logic.

### Runtime Reality

The system documentation repeatedly shows a hybrid runtime model:

- hosted NVIDIA-compatible reasoning path as primary
- private / local alternatives possible
- runtime abstraction should outlive vendor choice

---

## 14. Data Model and Core Entities

The major persistent entities reflected across the docs are:

- users and roles
- leads and lead intelligence
- inventory and project data
- perception sessions
- CCTV events
- vault assets and opens
- omnichannel logs
- page revisions and canvas components
- model catalog and hydration state
- machine sessions and cost records

### Persistent Truth

PostgreSQL is the primary source of truth for operational data.  
S3 is becoming the canonical store for large model and asset artifacts.  
AWS GPU NVMe is treated as fast ephemeral runtime cache, not authoritative storage.

---

## 15. Infrastructure and Deployment Model

Project Velocity now has a clear split between:

- **stable control surfaces**
- **ephemeral compute workers**
- **canonical storage**

### Current Deployment Pattern

- Linux box:
  - long-lived control surface
  - private origin services
  - operator tooling
- AWS t4g ingress:
  - stable public edge
  - route manager
- AWS GPU instances:
  - disposable compute nodes
  - ComfyUI and model workloads
- S3:
  - canonical model / workflow / asset store

### Architectural Principle

This is not “one giant computer.”  
It is:

- one control plane
- one ingress plane
- one durable asset plane
- many disposable compute workers

That is the correct model.

---

## 16. Stable Ingress Layer

The stable ingress layer is the permanent public front door.

### Purpose

- stable public IP
- DNS target for public routes
- TLS termination
- hostname-based routing
- forwarding to Linux or AWS backends

### Current Public Surfaces

The handoff documents establish these public hostnames as part of the route model:

- `office.desineuron.in`
- `git.desineuron.in`
- `cloud.desineuron.in`
- `projects.desineuron.in`
- `talk.desineuron.in`
- `vpn.desineuron.in`
- `comfy.desineuron.in`
- `ops.desineuron.in`

### Key Design Principle

Backends may change. Public identity should not.

That is why:

- GPU workers should not own the stable Elastic IP
- the ingress box should stay alive and route based on managed config

---

## 17. Linux AWS Control Surface

The Linux box is now the operational control surface for AWS.

### Responsibilities

- machine lifecycle management
- preferred instance selection
- spot/on-demand visibility
- session and cost tracking
- route management through ingress
- model ingest and hydration orchestration
- operator UI and CLI

### Canonical Asset Strategy

The documentation evolution shows a strong convergence:

- Linux can store local copies
- but S3 should be the canonical large-model source for ephemeral AWS hydration

That is the right direction because S3 is:

- durable
- AWS-native
- fast to hydrate with `s5cmd`
- not dependent on home network conditions

### Control Plane Flow

```mermaid
flowchart TD
    A[Operator UI / CLI on Linux] --> B[Launch AWS Worker]
    B --> C[Worker Bootstrap]
    C --> D[Hydrate from S3]
    D --> E[Verify Manifest]
    E --> F[Start Workload]
    F --> G[Map Route Through Ingress]
    G --> H[Track Runtime / Cost / Logs]
```

---

## 18. Operating Flows

### Lead Intelligence Flow

- lead enters through channel
- Oracle / backend receives it
- tagging and enrichment happen
- lead lands in CRM operating surface

### Sentinel Session Flow

- broker runs session
- MediaPipe emits perception packets
- backend computes QD and updates lead/session state
- notifications stream back in real time

### Dream Weaver / Comfy Flow

- operator or app triggers generation
- GPU worker receives workflow
- model hydrates if missing
- ComfyUI or pipeline runs
- output is returned or archived

### Infra Control Flow

- operator selects profile
- Linux control surface launches worker
- route gets mapped through ingress
- workload is exposed without changing public identity

---

## 19. Security, Privacy, and Sovereignty

Project Velocity’s strongest recurring architectural doctrine is data sovereignty.

### Security Principles

- client data belongs to client
- on-prem or client-controlled cloud must be supported
- zero-trust between services
- least privilege for machine roles
- no hidden production dependencies on developer laptops
- auditability matters for both operations and business decisions

### Privacy Positioning

Velocity is explicitly positioned as anti-SaaS in the strategic docs.

That means product delivery should support:

- on-prem deployment
- client-owned cloud
- local or sovereign runtime options
- explicit consent and audit around biometric flows

This is not just a compliance detail. It is a core selling argument.

---

## 20. Current Live Truth

Based on the most recent infrastructure handoff and operational truth docs, the current live picture is:

- stable ingress is running on AWS `t4g.micro`
- Linux box is the long-lived origin and control surface
- ComfyUI is exposed through managed ingress routing
- auto-heal exists for:
  - home IP sync
  - Comfy route sync
- ops control plane is live on Linux
- S3 is in place as the canonical control-plane bucket

Important operational truths that should not be lost:

- GPU nodes are ephemeral and should be treated that way
- route management should be dynamic, not hardcoded
- NVMe is for speed, not truth
- Linux and S3 together are the operational backbone

---

## 21. Build Priorities and Open Gaps

The documentation implies this priority order:

1. stabilize control plane and ingress
2. stabilize model hydration and GPU orchestration
3. finish Oracle backend/runtime implementation
4. continue iOS and web convergence
5. standardize packaging for on-prem delivery

### Open Gaps

- Oracle production runtime is not fully wired yet
- several frontend surfaces still rely on mock or transitional behavior
- deployment packaging for customer installs is not yet standardized enough
- multi-property / portfolio product packaging needs formalization in product artifacts
- some business docs are strong on thesis but still need conversion into installable product contracts

---

## 22. Runbooks and Team Usage

### What the team should point to for truth

- **this master bibel** for unified product and architecture truth
- **ingress handoff** for current infra routing truth
- **ops control plane bibel** for operator workflows

### When a new service is added

The team should define:

- what plane it belongs to
- whether it is stable or ephemeral
- where its truth is stored
- how it is routed publicly
- which system owns its startup, health, and recovery

### Operational Rule

If a workflow depends on a developer’s Windows laptop staying alive, it is not production-ready.

---

## 23. Source Lineage Map

This master bibel draws primarily from these source families:

### Product and architecture

- `Project Velocity - The Oracle.md`
- `The Sentinel Bibel.md`
- `velocity_technical_bible.md`
- `velocity_ios_bible.md`
- `oracle_development_status.md`

### Visual generation

- `DREAMWEAVER_TECHNICAL_SPEC.md`
- `A100_DEPLOYMENT_VALIDATION.md`
- `comfy_engine/scripts/README.md`
- `Project Velocity_ Dream Weaver.md`

### Infra and operations

- `TEAM_HANDOFF_2026-04-08.md`
- `Desineuron Ops Control Plane Bibel.md`
- `nemoclaw_setup_truth.md`
- `infrastructure_deployment_manifest.md`
- ingress and ops READMEs

### Business and GTM context

- `Velocity Kolkata Customer 0 Strategy - Get My Ghar.md`
- `Kolkata Builder Intel and Meeting Map - April 2026.md`
- `Customer Personas for Abu Dhabi and Dubai...md`
- sprint user story docs

### Prompt and AI behavior contracts

- `backend/nemoclaw_prompts/*.md`

---

## Final Position

Project Velocity is best understood as a sovereign, modular real-estate operating system with:

- premium user surfaces
- AI-driven CRM and perception intelligence
- property-linked generation workflows
- a private operational backbone
- a route-stable ingress layer
- a Linux-hosted control plane
- S3-backed canonical model and asset strategy

That is the coherent architecture the scattered docs were already converging toward.