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

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

## 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:

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