Velocity-OS/README.md

Velocity-OS

Velocity-OS is the simplified production shell for Project Velocity: an AI-assisted operating system for real estate sales, client intelligence, property media, campaign work, and admin control.

The goal is not to copy the old Project_Velocity UI screen-for-screen. The goal is to preserve the useful capabilities, reduce the surface area, and make the system usable through three clear work modes.

Architecture At A Glance

Velocity-OS/
|-- webos/          React 19, React Router, Framer Motion, Zustand, TanStack Query
|-- core/           FastAPI, PostgreSQL access, CRM APIs, Oracle natural DB agent
|-- media-engine/   Dream Weaver gateway for image generation / virtual staging
|-- agents/         Agent/runtime integration surface
|-- infrastructure/ Deployment, model hydration, gateway, and runtime operations

Primary Surfaces

Pillar	Route	What It Replaces From Project_Velocity
Command	/command	Dashboard, Oracle prompt surface, priority signals
Oracle	/oracle	Full Oracle canvas/chat workspace, chat recents, SQL-backed result cards
Pipeline	/pipeline and /pipeline/:personId	CRM, leads, Client 360, conversations, tasks, showroom flow
Studio	/studio and /studio/:propertyId	Inventory, property pages, media gallery, Dream Weaver / Reimagine, campaigns
Control Room	/control-room/:panel?	Admin settings, Oracle/schema controls, comms settings, users, model hydration

Project_Velocity To Velocity-OS Migration Matrix

Project_Velocity capability	Velocity-OS location	Migration state	Notes
Login, session, current user, guarded routes	webos/src/auth, core/api/api/routes_auth.py	Migrated	Uses token-backed authenticated shell.
Dashboard KPIs and priority signals	/command	Migrated	Command keeps the old dashboard intent but removes low-value page sprawl.
Lightweight Oracle ask box	/command	Migrated	The prompt bar now submits to Oracle and saves a chat session.
Full Oracle Canvas workspace	/oracle	Migrated	Added as a first-class nav item so the chat/canvas surface is no longer orphaned.
Oracle recents, new chat, search, share/export	/oracle	Migrated locally	Recents persist in browser storage; share currently exports chat JSON to clipboard.
Oracle natural DB query	core/oracle/oracle/natural_db_agent.py, /api/oracle/query	Migrated	Backend remains the source of truth for SQL-backed CRM answers.
Oracle JSON codebook and component templates	core/oracle/oracle/*.json	Migrated	JSON is not counted as JavaScript in repo language stats; absence of a JS bar does not mean the codebook is missing.
Oracle schema catalog and data health	core/api/api/routes_oracle.py	Migrated	Exposed for diagnostics and planner context.
Canvas revisions/share/fork server workflow	Legacy Oracle backend plus new /oracle shell	Partial	Backend concepts exist; new Velocity-OS UI currently prioritizes chat/result generation and local export.
CRM pipeline board	/pipeline board view	Migrated	Uses canonical CRM API and normalized response shapes.
CRM pipeline list	/pipeline list view	Migrated	Board/list now render different layouts from the same normalized data.
Client 360 profile	/pipeline/:personId	Migrated	Uses tolerant ID and response normalization for old/new backend shapes.
Conversations, intelligence, properties, tasks	/pipeline/:personId tabs	Migrated	Consolidates old CRM/comms/intelligence surfaces into one entity page.
Showroom/webcam mode	/pipeline/:personId showroom action	Migrated	Preserves the Project_Velocity video/webcam concept inside Client 360.
WhatsApp/comms provider config	/control-room/comms-config plus Client 360	Partial	UI and API wiring are present; live send/record/transcribe depends on configured provider credentials.
Inventory properties	/studio properties tab	Migrated	Uses Studio API normalization.
Property detail and media gallery	/studio/:propertyId	Migrated	Includes floorplan, media, overview, and actions.
Dream Weaver / Reimagine	/studio/:propertyId Reimagine	Migrated	Supports image upload, prompt text, async job polling, generated preview, open, and download.
Campaigns / Meta ads	/studio campaigns tab and /control-room/meta	Partial	Campaign list UI/API exists; Meta execution depends on live integration credentials.
Control Room admin panels	/control-room/:panel?	Migrated	Reworked to match the dark Velocity-OS theme and current L4/SGLang runtime truth.
Runtime LLM/SGLang operational truth	Control Room model hydration and docs	Migrated as ops surface	Heavy model runtime remains backend/infrastructure, not a WebOS feature page.
iPad/mobile backend support	core/api shared endpoints	API migrated	Native iPad client consumes the same backend contracts; not duplicated as a WebOS page.

Runtime Truths

• The public app is served from https://velocity.desineuron.in/.
• Frontend API calls go through the same origin unless VITE_API_URL is set.
• Dream Weaver uses multipart image upload through /dream-weaver, then polls /dream-weaver/status/{job_id}, then downloads from /dream-weaver/result/{job_id}.
• The deployed GPU reality is the Desineuron AWS GPU worker, currently oriented around 4 x NVIDIA L4 for inference/runtime work. Do not assume the placeholder RTX 6000/MIG text from older mock screens is operational truth.
• Large model and media runtime assets belong on GPU NVMe, not Linux root disk.

Oracle Canvas And JSON Schemas

Velocity-OS imports the Project_Velocity Oracle JSON codebook assets required for canvas/component planning:

• core/oracle/oracle/oracle_runtime_codebook_merged.json
• core/oracle/oracle/oracle_template_seed_db.json

The loader lives at:

• core/oracle/oracle/codebook_service.py

The loader now resolves the native Velocity-OS paths first, with legacy backend/oracle paths only as compatibility inputs. A quick sanity check should report the large runtime codebook:

python -c "from core.oracle.oracle.codebook_service import codebook_service; print(codebook_service.stats())"

Expected current result:

example_count: 2395
template_count: 1320
source_summary includes runtime_merged:2395

Oracle natural query flow:

1. The user asks a question in Command.
2. webos/src/pillars/command/OracleBar.tsx posts { prompt, context } to /api/oracle/query.
3. core/api/api/routes_oracle.py calls the Oracle natural DB agent.
4. The result returns SQL-backed rows, columns, warnings, and source tables.
5. OracleResultCard renders the result as a metric, list, or table based on the returned data shape.

Studio And Reimagine

Studio uses:

• webos/src/shared/hooks/useStudio.ts for inventory/property normalization.
• webos/src/pillars/studio/StudioPillar.tsx for property and campaign lists.
• webos/src/pillars/studio/PropertyEntity.tsx for the property detail page.
• webos/src/pillars/studio/ReimaginePanel.tsx for Dream Weaver.

Reimagine currently supports:

• source room image upload
• room type selection
• freeform styling prompt
• async Dream Weaver job submission
• polling without blocking the page
• generated image preview
• generated image download/open actions

Control Room

Control Room is admin-only and route-driven:

• /control-room/system
• /control-room/oracle-admin
• /control-room/comms-config
• /control-room/users
• /control-room/models
• /control-room/meta

The selected panel is derived from the URL. This avoids stale local state when users navigate directly or return from another page.

Local Development

Frontend:

cd webos
npm install
npm run dev

Production build check:

cd webos
npm run type-check
npm run build

Backend:

cd core
python -m uvicorn api.main:app --host 127.0.0.1 --port 8001 --reload

Important environment variables:

• VITE_API_URL overrides the frontend API origin.
• VITE_DREAM_WEAVER_URL overrides Dream Weaver gateway origin.
• VITE_DREAM_WEAVER_API_KEY adds the optional Dream Weaver gateway key.
• Backend database settings are provided by the running deployment environment.

Verification Checklist

Run before handoff:

• npm run type-check from webos
• npm run build from webos
• Oracle codebook stats check from repo root
• Login to https://velocity.desineuron.in/
• Open Command and submit an Oracle question
• Open Pipeline, switch Board/List, open a client, return to Pipeline without refresh
• Open Studio, switch Properties/Campaigns, open a property, use Reimagine upload + prompt
• Open Control Room and verify dark theme across all panels

Known Engineering Notes

• The production build still warns that the Three.js vendor chunk is large. This is not a functional failure, but Studio 3D/media should remain lazy-loaded and can be split further later.
• The app intentionally keeps Project_Velocity as a source/reference repository. Velocity-OS should import only the required code/data assets, not blindly mirror the old structure.