sagnik/Project_Velocity
2
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Missed files

Browse Source
This commit is contained in:
Sagnik
2026-04-12 19:25:43 +05:30
parent 4645ff737b
commit d77373900a
69 changed files with 4375 additions and 2469 deletions
Download Patch File Download Diff File Expand all files Collapse all files

875
.Agent Context/Bibels/Project Velocity Master Bibel.md Normal file
View File

@@ -0,0 +1,875 @@
# 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.