# 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

```text
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:

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

Expected current result:

```text
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:

```powershell
cd webos
npm install
npm run dev
```

Production build check:

```powershell
cd webos
npm run type-check
npm run build
```

Backend:

```powershell
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.