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

The Three Pillars

Pillar	Route	What It Replaces From Project_Velocity
Command	/command	Dashboard, Oracle prompt surface, priority signals
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

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.