Project_Velocity/README.md

# Project Velocity

Project Velocity is an on-prem real estate operating system for high-value property sales.
It combines a premium WebOS, an iPad field app, a FastAPI neural core, ComfyUI-based media generation, and biometric/sentiment-assisted sales intelligence.

This repository is the active product codebase for the Velocity suite.

## At A Glance

| Area | Current State |
| --- | --- |
| WebOS | Live UI shell with Dashboard, Oracle, Sentinel, Inventory, Catalyst, and Settings |
| Backend | Unified FastAPI backend with PostgreSQL, auth, Sentinel, Catalyst, CCTV, scenes, videos, and vault |
| iPad | Materially implemented app surface for inventory, camera flows, and Time & Light |
| AI Media | Dream Weaver, Qwen, and Wan workflow assets present locally |
| Infra | Linux control surface, AWS GPU workers, stable ingress, and S3-backed asset strategy |

## Product Surfaces

- `Velocity WebOS`
  - operator console for sales, inventory, perception, and marketing
- `The Oracle`
  - AI-assisted lead intelligence and analytical workspace
- `The Sentinel`
  - live perception, sentiment, and showroom engagement tracking
- `Inventory / Time & Light`
  - property inventory surfaces and light-analysis tooling
- `The Catalyst`
  - marketing campaign orchestration and asset generation
- `iPad App`
  - field-facing app for inventory, camera workflows, and time/light experience
- `Neural Core`
  - unified FastAPI backend with PostgreSQL, auth, Sentinel, Catalyst, CCTV, scenes, videos, and vault services

## Product Screens

### Dashboard

![Velocity Dashboard](docs/images/readme/dashboard.png)

### The Oracle

![The Oracle](docs/images/readme/oracle.png)

### The Sentinel

![The Sentinel Overview](docs/images/readme/sentinel-overview.png)

![The Sentinel Live Session](docs/images/readme/sentinel-live-session.png)

### Inventory

![Inventory](docs/images/readme/inventory.png)

### The Catalyst

![The Catalyst](docs/images/readme/catalyst.png)

### Settings

![Settings](docs/images/readme/settings.png)

## Architecture

```mermaid
flowchart LR
    ipad[iPad App] --> webapi[FastAPI Neural Core]
    webos[Velocity WebOS] --> webapi
    webapi --> pg[(PostgreSQL)]
    webapi --> sentinel[Sentinel Engine]
    webapi --> catalyst[Catalyst Routes]
    webapi --> vault[Vault Links]
    webapi --> cctv[CCTV / Scene / Video Routers]
    catalyst --> comfy[ComfyUI / Dream Weaver / Wan / Qwen]
    comfy --> s3[S3 Model + Asset Store]
    comfy --> gpu[AWS GPU Workers]
    webos --> ingress[t4g Ingress]
    ipad --> ingress
    ingress --> webapi
    ingress --> comfy
```

## Stack

### Frontend

- `React 19`
- `Vite`
- `TypeScript`
- `Tailwind`
- `Framer Motion`
- `Recharts`
- `Zustand`

### Backend

- `FastAPI`
- `PostgreSQL`
- `WebSockets`
- `JWT auth`
- `asyncpg`

### AI / Media

- `ComfyUI`
- `Dream Weaver`
- `Qwen image workflows`
- `Wan 2.2 workflow assets`
- `Sentinel perception pipeline`
- `Google MediaPipe browser-side face landmarking`

### Infrastructure

- Linux control surface
- AWS GPU workers
- stable `t4g.micro` ingress
- S3-backed model and asset strategy
- route-managed Comfy exposure

## Quick Start

### Web frontend

```bash
cd app
npm install
npm run dev
```

Default local URL:

```text
http://127.0.0.1:5173/
```

### Backend

```bash
python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
```

Health check:

```text
http://127.0.0.1:8000/health
```

## Repository Areas

| Path | Purpose |
| --- | --- |
| `app/` | Velocity WebOS frontend |
| `backend/` | FastAPI neural core |
| `iOS/` | native iPad application |
| `comfy_engine/` | Dream Weaver, Wan, Qwen workflow logic and assets |
| `infrastructure/` | ingress, ops, deployment, and recovery artifacts |
| `.Agent Context/` | working docs, bibels, strategy, and truth artifacts |

## Runtime Coverage

### WebOS modules

- Dashboard
- The Oracle
- The Sentinel
- Inventory
- The Catalyst
- Settings

### Backend capabilities already present

- authentication and token issuance
- authenticated `/api/auth/me` identity resolution with `full_name` and email
- Catalyst campaign routes
- Sentinel websocket/session ingestion
- canonical CRM routes for contacts, client 360, opportunities, tasks, kanban, QD, and imports
- Oracle v1 API routes with same-origin frontend fallback
- CCTV routes
- scenes and videos routes
- vault routes
- static asset serving
- health checks

### Media and generation paths

- Dream Weaver workflow stack exists locally
- Qwen poster workflow assets exist locally
- Wan 2.2 workflow assets exist locally
- queue/gateway model exists and is being hardened into a canonical async path

## Positioning

Velocity is not built as a SaaS-first CRM.
It is designed as a private deployment system for builders, channel partners, and enterprise real-estate operators who want:

- private data ownership
- on-prem or client-controlled deployment
- AI-assisted sales acceleration
- perception-assisted showroom intelligence
- high-end marketing asset generation
- portfolio-aware expansion over time

## Current Delivery Status

Implemented now:

- strong WebOS UI shell
- real iOS implementation surface
- live FastAPI backend
- live ingress and AWS/Linux operational model
- Dream Weaver / Qwen / Wan workflow assets
- browser-webcam Sentinel path using MediaPipe
- canonical CRM schema and synthetic Kolkata client dataset
- Oracle CRM-facing route family and Client 360 aggregation service
- Sentinel assigned-mode integration with canonical CRM contacts
- same-origin Oracle frontend client fallback for production deployments
- Linux-origin auto-update scripts and nginx deployment assets under `infrastructure/desineuron_ingress/`

Still being closed:

- prompt inventory and persona contract map
- full end-to-end async orchestration across all media workflows
- live operational proving of the import review and commit workflow
- richer Sentinel evidence capture at emotion hotpoints
- full production rollout validation on the Linux origin after each merge

## Deployment Model

Velocity is being shaped toward:

- `on-prem primary`
- `client-owned cloud optional`
- `Linux control surface as operator plane`
- `AWS GPU workers as elastic compute`
- `S3 as canonical model and large-asset store`

The current repo also includes the ingress and ops artifacts used to run this model today.

### Linux-origin update path

The repo includes a Linux-side auto-deploy path for `velocity.desineuron.in`:

- [`deploy_velocity_site.sh`](infrastructure/desineuron_ingress/deploy_velocity_site.sh)
- [`install_linux_velocity_site.sh`](infrastructure/desineuron_ingress/install_linux_velocity_site.sh)
- [`desineuron-velocity-site-update.service`](infrastructure/desineuron_ingress/desineuron-velocity-site-update.service)
- [`desineuron-velocity-site-update.timer`](infrastructure/desineuron_ingress/desineuron-velocity-site-update.timer)
- [`velocity.desineuron.in.nginx.conf`](infrastructure/desineuron_ingress/velocity.desineuron.in.nginx.conf)

That path is designed to pull `main` from Gitea onto the Linux origin, rebuild the frontend, and republish the static site under `/var/www/velocity.desineuron.in/current`.

## Internal Truth Sources

Key internal docs live under `.Agent Context/` and `infrastructure/`.
Important current references include:

- `Project Velocity Master Bibel`
- `Sprint 1 Fact Table`
- `TEAM_HANDOFF_2026-04-08.md`

## Status

This is an active product repository, not a cleaned SDK.
Expect a mix of:

- production-bound code
- live infrastructure artifacts
- design explorations
- strategic docs
- work-in-progress subsystem convergence

The main direction is stable:
Velocity is converging into a private, modular, on-prem real estate operating system with AI, perception, and media generation as first-class components.