forked from sagnik/Velocity-OS
177 lines
9.1 KiB
Markdown
177 lines
9.1 KiB
Markdown
# 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.
|