Project_Velocity/.Agent Context/Sayan's Docs/Project Velocity Software SOT 1.md

Project Velocity Software Source of Truth

Document owner: Project Velocity engineering/product analysis
Prepared for: Sayan and the Desi Neuron team
Generated from codebase inspection on: 2026-04-29
Repository root: /Users/sayan/Desi Neuron/Project_Velocity

1. Executive Summary

Project Velocity is a multi-surface real estate operating system. It combines a WebOS command center, a native iPad operator app, an Android edge phone companion, a FastAPI backend, CRM and mobile-edge data models, AI-driven Oracle/Sentinel modules, Catalyst marketing surfaces, and a Dream Weaver image transformation pipeline powered by a local/remote ComfyUI gateway.

The codebase is not a single app. It is a platform with these major product surfaces:

• Velocity WebOS: React/Vite desktop web application used as the primary command center.
• Velocity iPad: native Swift iPad application for field operators, CRM, calendar, inventory, Dream Weaver, and mobile operations.
• Velocity Edge Phone: native Android phone companion for alerts, leads, notes, communications, and transcripts.
• Velocity Neural Core: FastAPI backend that exposes CRM, auth, mobile-edge, Catalyst, Oracle, Sentinel, inventory, comms, observability, admin, and runtime LLM APIs.
• Dream Weaver gateway: FastAPI gateway in comfy_engine that bridges Velocity clients to ComfyUI workflows.
• Infrastructure and operations: AWS, Caddy, rathole tunnel, route sync, GPU service management, and an Ops Control Plane.

The system already contains substantial production-oriented work: tenant-aware authentication, canonical CRM import and task APIs, iPad local fallback behavior, Dream Weaver route contracts, Oracle canvas APIs, admin health/queue surfaces, and observability foundations. The largest remaining risks are external dependency readiness, incomplete persistence on some WebOS modules, production hardening of Comfy/Dream Weaver jobs, and gaps between rich frontend prototypes and fully wired backend execution.

2. Product Thesis

Velocity is designed as an operating layer for real estate sales, marketing, and field execution. The platform attempts to connect:

• CRM lead intelligence and client 360 context.
• Property inventory and visual sales collateral.
• Sales team tasks, calls, notes, events, reminders, and follow-ups.
• AI Oracle workflows for executive intelligence and canvas-based analysis.
• Sentinel perception workflows for live session/visitor intelligence.
• Catalyst marketing workflows for ad campaigns, ROI, and creative generation.
• Dream Weaver visual staging workflows for transforming room images.
• Edge mobile surfaces for real-time field capture and mobile memory.

The architectural direction is correct for a product-grade platform: a canonical backend, native apps for operator-specific UX, a WebOS for central operations, and external AI/marketing/comms integrations behind service adapters.

3. Repository Map

Path	Purpose	Current status
app/	Velocity WebOS React/Vite frontend	Active and feature-rich
backend/	FastAPI backend and service layer	Active, broad API surface
iOS/velocity-ipad/	Native Swift iPad app	Active, production-oriented
android-edge-phone/	Native Android edge phone app	Active companion surface
android-tablet/	Android tablet project scaffold	Build scaffold only, no full app observed
comfy_engine/	Dream Weaver gateway, Comfy workflows, prompts, batch tooling	Active AI image pipeline
infrastructure/	AWS, ingress, Caddy, GPU routing, ops control plane	Active deployment/ops tooling
.Agent Context/	Planning, handoff, and analysis documents	Internal knowledge base

4. Runtime Architecture

High-level flow:

WebOS React App  ----\
iPad Swift App    ---->  FastAPI Backend / Velocity Neural Core  ---> PostgreSQL
Android Phone     ----/             |             |                 External providers
                                    |             |                 Meta, Google, WAHA/Evolution
                                    |             |
                                    |             ---> Dream Weaver Gateway ---> ComfyUI GPU
                                    |
                                    ---> Oracle / Sentinel / Runtime LLM services

Core runtime dependencies:

• PostgreSQL via asyncpg.
• JWT authentication and tenant-aware user context.
• ComfyUI for Dream Weaver image generation.
• Meta Marketing API and Google Ads-style integrations for Catalyst.
• WAHA/Evolution/mock providers for communications.
• LLM providers through the runtime LLM service.
• Optional GPU/runtime services for NemoClaw and Comfy workflows.

5. WebOS Application

Location: app/
Stack: React 19, Vite 7, TypeScript, Tailwind, Framer Motion, Recharts, Zustand, React Three Fiber, Drei, Radix UI, Playwright.

Main route owner: app/src/App.tsx

5.1 WebOS Routes

Route	Module	Component
/dashboard	Dashboard	Dashboard.tsx
/oracle	Oracle	Oracle.tsx and app/oracle/page.tsx
/sentinel	Sentinel	Sentinel.tsx
/inventory	Inventory	Inventory.tsx
/catalyst	Catalyst	Catalyst.tsx
/crm	CRM	CRM.tsx
/comms	Communications	Comms.tsx
/settings	Settings	Settings.tsx
/admin	Admin	app/admin/page.tsx

5.2 WebOS Shell, Auth, and Global State

The WebOS bootstraps user session from a stored Velocity token using getVelocityToken() and /api/auth/me. It supports login/logout, active module state, admin route gating, global navigation, and shared persisted state through Zustand.

Primary store: app/src/store/useStore.ts

Persisted state:

• Authenticated user.
• Active module.

In-memory shared state:

• Navigation collapse state.
• Oracle leads/messages.
• Sentinel visitors and alerts.
• Dashboard metrics.
• Inventory units.
• System status.
• Notifications.

Current status:

• Done: session restore, module routing, admin gating, shared state primitives.
• Limitation: many module-specific records are fetched separately or kept in local stores and are not universally normalized into one frontend cache.

5.3 Dashboard

Component: app/src/components/modules/Dashboard.tsx

Purpose:

The Dashboard is the executive summary surface. It blends sales metrics, lead intelligence, conversations, inventory, velocity charting, pipeline activity, and mobile-edge alerts.

Key features:

• Lead book count and whale/high-intent lead count.
• Conversations and inventory summary cards.
• Velocity trend chart.
• Pipeline activity feed.
• Mobile-edge alert tiles from /api/mobile-edge/alerts.
• Store-backed stats for leads, messages, units, and system health.

Backend integration:

• Reads mobile-edge alerts.
• Relies on bootstrapped CRM/store data for several metrics.

Current status:

• Done: dashboard UI and blended metric layout.
• Partial: some metric sources are store/mock-derived rather than always canonical backend values.
• Left: production-grade metric contracts should be centralized so Dashboard numbers cannot drift from CRM/mobile-edge modules.

5.4 CRM

Component: app/src/components/modules/CRM.tsx
API helper: app/src/lib/crmApi.ts

Purpose:

The CRM is the founder/sales command center for contacts, pipeline, opportunities, tasks, and CSV imports.

Major views:

• Contacts.
• Kanban pipeline.
• Opportunities/deals.
• Tasks.
• Imports.
• Client 360 slide-over.

Features:

• Contact search and filtering.
• Buyer and status badges.
• Pagination.
• QD score bars.
• Client 360 panel with identity, QD context, property interests, opportunities, interactions, tasks, risks, and recommended actions.
• Kanban board by lead stage.
• Opportunity list with project, stage, value, probability, and next action.
• Pending task list.
• CSV import upload workflow.

Backend integration:

• Canonical CRM APIs under /api/crm.
• Legacy lead APIs under /api/leads.
• Kanban from /api/crm/kanban and legacy bridge.
• Client 360 from /api/crm/client-360/{person_id}.
• Imports from /api/crm/imports.
• Tasks from /api/crm/tasks.

Current status:

• Done: read-heavy CRM workflows, import upload entry, client 360 view, Kanban display, opportunities and tasks lists.
• Partial: full import review/commit workflow exists in backend but frontend review UX is still lightweight.
• Partial: not all CRM edit/create operations are exposed as polished WebOS flows.
• Left: complete CRUD UX for contacts, tasks, opportunity stage editing, import review proposals, and conflict resolution.

5.5 Communications

Component: app/src/components/modules/Comms.tsx
API helper: app/src/lib/commsApi.ts

Purpose:

The Communications module provides a WhatsApp/call-style operator inbox with threads, messages, notes, and CRM linkage.

Features:

• Thread list.
• Message list.
• Send message with optimistic UI.
• Link thread to person.
• Notes/tasks API helper support.
• Fallback mock threads/messages when backend is unavailable.

Backend integration:

• /api/comms/threads
• /api/comms/threads/{thread_id}
• /api/comms/threads/{thread_id}/messages
• /api/comms/threads/{thread_id}/messages
• /api/comms/threads/{thread_id}/link-person
• /api/comms/notes
• /api/comms/tasks
• /api/comms/settings
• /api/comms/provider/test
• /api/comms/webhooks/{provider}

Current status:

• Done: usable inbox UI and backend-backed message flows.
• Partial: provider integration depends on WAHA/Evolution credentials and deployment.
• Limitation: mock fallback can hide backend outages during local UX testing unless explicitly monitored.

5.6 Oracle

Components:

• app/src/components/modules/Oracle.tsx
• app/src/app/oracle/page.tsx

Purpose:

Oracle is the AI command/canvas system. It provides analysis modes, prompt-driven canvas generation, data lenses, revisions, forks, rollback, collaboration, and merge requests.

Major capabilities:

• Prompt modes: Pipeline, Team Performance, Account Timeline, Geographic Map, Calendar & Tasks, KPI Summary.
• Canvas pages and page revisions.
• Component selection and prompt rail.
• Forks and rollback.
• Merge request flow.
• Share modal.
• Client data lens.
• WebSocket collaboration route.

Backend integration:

• /api/oracle/health
• /api/oracle/data-health
• /api/oracle/schema-catalog
• /api/oracle/query
• /api/oracle/mcp/tools
• /api/oracle/mcp/execute
• /api/oracle/workflow/preview
• /api/oracle/actions
• /api/oracle/actions/{action_id}
• /api/oracle/actions/writeback
• /api/oracle/v1/canvas-pages
• /api/oracle/v1/canvas-pages/{page_id}
• /api/oracle/v1/canvas-pages/{page_id}/prompts
• /api/oracle/v1/ws/oracle/canvas/{page_id}

Current status:

• Done: advanced frontend canvas shell and backend route family.
• Partial: usefulness depends on available CRM data, LLM provider configuration, and Oracle service readiness.
• Left: broaden end-to-end tests for complete prompt-to-canvas-to-writeback workflows.

5.7 Sentinel

Component: app/src/components/modules/Sentinel.tsx
Live session component: app/src/components/modules/sentinel/SentinelLiveSession.tsx
Perception player: app/src/components/modules/sentinel/PerceptionPlayer.tsx

Purpose:

Sentinel is a perception and visitor intelligence module. It supports overview analytics and a live session workflow for media-driven lead intelligence.

Features:

• Overview tab with zone analytics, sentiment distribution, dwell time, alerts, strategic insights, and Journey River visualization.
• Live session mode with property video selection.
• Scene CSV upload.
• Assigned mode to bind a CRM contact.
• Auto mode intended for CCTV lead matching.
• MediaPipe-based face/perception handling in the browser.
• QD packet emission.

Backend integration:

• /api/videos/marketing
• /api/scenes/upload
• /api/scenes/{video_asset_id}
• /api/sentinel/consent
• /api/sentinel/session/complete
• /api/sentinel/tag-lead
• /api/sentinel/qd-score/{lead_id}
• /api/sentinel/ws/notifications
• /api/sentinel/ws/perception
• /api/cctv/event
• /api/cctv/finalize-auto-mode

Current status:

• Done: rich live session workflow and backend event ingestion routes.
• Partial: auto CCTV matching exists but needs stronger production UX and operational validation.
• Limitation: browser-side perception depends on media availability, model load, and operator flow discipline.

5.8 Inventory

Component: app/src/components/modules/Inventory.tsx

Purpose:

Inventory presents real estate units, model previews, floor plans, maps, media, and property detail exploration.

Features:

• Inventory stat cards.
• Search and filters.
• Grid/list layout.
• Detail modal.
• 3D model viewer using React Three Fiber and Drei.
• Floor plan/blueprint viewer with zoom/pan.
• Google map embed.
• Hardcoded penthouse visual references and local model assets.

Backend integration:

• Inventory backend exists under /api/inventory.
• WebOS UI currently relies heavily on frontend store/static data for units and previews.

Current status:

• Done: sophisticated visual frontend experience.
• Partial: backend inventory import/property/media APIs exist, but WebOS unit hydration is not fully canonical.
• Left: unify property/unit data model between backend and WebOS display, and connect media upload/management UX.

5.9 Catalyst

Component: app/src/components/modules/Catalyst.tsx

Purpose:

Catalyst is the marketing and campaign operations area. It contains multiple tabs for creative, campaign control, ROI, war room, marketing intelligence, and Dream Weaver.

Tabs:

• The Studio.
• Campaign Command.
• Intelligence & ROI.
• War Room.
• Marketing.
• Dream Weaver.

5.9.1 The Studio

Purpose:

Creative asset generation surface for visual AI workflows.

Features:

• Ground truth picker.
• Reference image slots.
• Image/video mode toggle.
• Prompt/keyword fields.
• Trigger render button.

Current status:

• Done: polished UI shell.
• Partial: the Studio send action is not a fully production-wired render pipeline in the inspected implementation.
• Left: connect generation action to a real backend route or Comfy/Catalyst asset pipeline.

5.9.2 Campaign Command

Purpose:

Campaign control and monitoring surface.

Features:

• Campaign summaries.
• Budget/bid-related command views.
• Store-driven campaign state.

Current status:

• Done: UI and local marketing store flows.
• Partial: some state is in-memory Zustand and not persisted.

5.9.3 Intelligence & ROI

Purpose:

Marketing performance visualization.

Features:

• Ad insight charting.
• ROI-style metrics.
• Recharts visualizations.

Current status:

• Done: analytics presentation.
• Partial: requires production data feeds for final accuracy.

5.9.4 War Room

Purpose:

Integration command surface for ad platform setup.

Features:

• Meta credential form.
• Local connected state.

Current status:

• Done: frontend setup flow.
• Partial: settings are local frontend state unless paired with backend/provider persistence.

5.9.5 Marketing

Component: app/src/components/modules/CatalystMarketingTab.tsx

Purpose:

Integrated marketing intelligence surface.

Features:

• Campaign manager.
• Lead intelligence feed.
• Sentiment scatter.
• Lead demographics.
• Platform status cards.

Backend integration:

• /api/catalyst/campaigns
• /api/analytics/sentiment-scatter
• /api/analytics/demographics

Current status:

• Done: backend-backed marketing intelligence tab.
• Partial: Meta/Google production data depends on provider credentials and SDK readiness.

5.9.6 Dream Weaver

Component: app/src/components/modules/CatalystDreamWeaverTab.tsx
API helper: app/src/lib/dreamWeaverApi.ts

Purpose:

WebOS implementation of the Dream Weaver room image transformation pipeline, aligned with the iPad app and Comfy gateway route contract.

Features:

• Upload source room image.
• Select room type.
• Enter style keywords.
• Gateway health badge.
• Route verification.
• ComfyUI/checkpoint readiness display.
• Generate button gated by source image, route, Comfy, and checkpoint readiness.
• Job submission to Dream Weaver gateway.
• Polling every 2 seconds.
• Result image fetch and display.
• Recent render history.
• Gateway contract display.

Backend/gateway integration:

• GET /health
• GET /dream-weaver/status/velocity-route-probe
• POST /dream-weaver
• GET /dream-weaver/status/{job_id}
• GET /dream-weaver/result/{job_id}

Configuration:

• VITE_DREAM_WEAVER_URL
• VITE_DREAM_WEAVER_API_KEY
• Development fallback: http://127.0.0.1:8082

Current status:

• Done: production-shaped WebOS Dream Weaver tab, no live optimization feed on this page.
• Partial: actual image generation depends on Dream Weaver gateway, ComfyUI availability, and a compatible checkpoint being hydrated.
• Limitation: gateway jobs are in-memory unless a durable store is added.

5.10 Settings

Component: app/src/components/modules/Settings.tsx

Purpose:

Operator configuration and environment visibility.

Features:

• System status cards.
• Companion surface status.
• Profile settings and avatar upload.
• Notifications.
• Security controls.
• Display/currency settings.
• Communications settings.
• Provider testing.
• Data export/cache clear.
• About section.

Current status:

• Done: broad settings shell and several live integration points.
• Partial: some settings are local-only or helper-backed, depending on module.
• Left: centralize user preferences and environment configuration in backend-backed settings tables.

5.11 Admin

Component: app/src/app/admin/page.tsx

Purpose:

Admin-only operational surface.

Features:

• Health checks.
• Queues.
• Installs.
• Actions.
• Logs.
• Templates.
• Synthetic jobs.

Backend integration:

• /api/admin-surface/health
• /api/admin-surface/queues
• /api/admin-surface/installs
• /api/admin-surface/actions
• /api/admin-surface/logs
• /api/admin-surface/templates
• /api/admin-surface/template-chapters
• /api/admin-surface/synthetic-jobs

Current status:

• Done: route exists and is admin-gated.
• Partial: operational usefulness depends on backend deployment and queue/job population.

6. iPad Application

Location: iOS/velocity-ipad/velocity/
Stack: SwiftUI, native iPadOS, URLSession-style API client, UserDefaults local fallback, ARKit/SceneKit for inventory sun overlays.

Primary files:

• VelocityApp.swift
• ContentView.swift
• Core/AppStore.swift
• Core/VelocityAPIClient.swift
• Core/ComfyClient.swift
• Features/*

6.1 iPad Navigation

The iPad app uses a NavigationSplitView with these sections:

• Dashboard.
• Clients.
• Imports.
• Communications.
• Calendar.
• Oracle.
• Sentinel.
• Inventory.
• Settings.

The app is gated by ConfigurationGateView until session configuration is available.

6.2 iPad AppStore

File: iOS/velocity-ipad/velocity/Core/AppStore.swift

Responsibilities:

• Owns shared app state.
• Refreshes contacts, tasks, kanban, opportunities, properties, calendar events, alerts, and lead events.
• Persists locally mutated tasks.
• Persists locally hidden task IDs.
• Persists locally created calendar events.
• Provides backend fallback behavior for recoverable failures.
• Maintains metrics such as lead count, whale lead count, property count, today calendar count, pending tasks, urgent tasks, pending insights, and pending transcriptions.

Current status:

• Done: strong production-minded state management with local resilience.
• Limitation: UserDefaults fallback is not a substitute for canonical backend persistence and cross-device sync.

6.3 iPad API Client

File: iOS/velocity-ipad/velocity/Core/VelocityAPIClient.swift

Supports:

• Contacts.
• Leads.
• Events.
• Calendar events create/update/cancel.
• Properties.
• Kanban board and lead stage movement.
• Client 360.
• Opportunities and opportunity updates.
• Import batches, review, and commit.
• Tasks and task status updates.
• Mobile-edge alerts.

Current status:

• Done: broad live backend client.
• Limitation: functionality depends on correct backend URL, auth token, and tenant context.

6.4 iPad Dashboard

File: Features/Dashboard/DashboardView.swift

Purpose:

Operator dashboard for live metrics and health signals.

Current status:

• Done: feature exists and is app-store backed.
• Left: ensure dashboard metric definitions match WebOS definitions to avoid cross-surface discrepancies.

6.5 iPad Clients

Purpose:

Mobile client/lead intelligence surface.

Current status:

• Done: live client data integration exists through shared store and API client.
• Left: maintain parity with WebOS Client 360 as canonical CRM evolves.

6.6 iPad Imports

File: Features/Imports/ImportsView.swift

Purpose:

CRM import monitoring/review surface.

Backend integration:

• Canonical CRM import batch routes.

Current status:

• Done: import feature present.
• Partial: full import remediation UX should be validated against backend review/commit semantics.

6.7 iPad Communications

File: Features/Communications/CommunicationsView.swift

Purpose:

Operator communications and follow-up surface.

Current status:

• Done: module present and connected through app data patterns.
• Left: keep WebOS and iPad communications behavior aligned with provider production readiness.

6.8 iPad Calendar

File: Features/Calendar/CalendarView.swift

Purpose:

Operator scheduling surface for CRM follow-ups and calendar events.

Features:

• Week grid.
• Day task list.
• Create Event button and modal.
• Title, client, all-day, duration, start, end, location, description, and task type controls.
• Normal Task and Confirmed Task status selection.
• Action popover per task/event.
• Normal task actions: Mark confirmed, Mark done, Snooze 2h, Snooze 1 Day, Cancel task.
• Confirmed task actions: Set Normal, Mark done, Snooze 2h, Snooze 1 Day, Cancel task.
• Done task behavior: shows Done badge and only Remove Task action.
• Cancelled tasks can be undone from the green banner.
• Banner feedback auto-dismiss behavior.
• Local fallback for create/update/cancel when recoverable backend failures occur.
• Counts update for active, confirmed, pending, done, removed, and cancelled states.

Backend integration:

• /api/mobile-edge/calendar
• /api/mobile-edge/calendar/{id}
• /api/crm/tasks
• /api/crm/tasks/{reminder_id}

Current status:

• Done: deeply developed and backend-synced with local fallback.
• Limitation: locally persisted fallback events survive rebuilds but not uninstall/app data reset. Backend persistence remains the production-grade source.

6.9 iPad Oracle

File: Features/Oracle/OracleView.swift

Purpose:

iPad Oracle client for executive/operator intelligence.

Current status:

• Done: module exists with mode availability gating.
• Partial: final usefulness depends on Oracle backend, CRM data readiness, and LLM availability.

6.10 iPad Sentinel

Files:

• Features/Sentinel/SentinelView.swift
• Features/Sentinel/SentinelScope.swift

Purpose:

iPad Sentinel client for field perception/intelligence workflows.

Current status:

• Done: module exists.
• Partial: must stay aligned with WebOS live session and backend perception contracts.

6.11 iPad Inventory

Files:

• Features/Inventory/InventoryView.swift
• Features/Inventory/SunseekerViewModel.swift
• Features/Inventory/ARSunOverlayView.swift
• Features/Inventory/SimulatorSunOverlayView.swift
• Features/Inventory/InventoryModeAvailability.swift

Purpose:

Native inventory and property visualization, including solar/sun overlay functionality.

Features:

• Inventory browsing.
• AR sun overlay.
• Simulator sun overlay.
• Sun calculations.
• Mode availability gating.
• Dream Weaver/Comfy client support through shared core.

Current status:

• Done: sophisticated native inventory features exist.
• Partial: production value depends on canonical inventory data completeness and media/model asset readiness.

6.12 iPad Dream Weaver Client

File: Core/ComfyClient.swift

Purpose:

The iPad Dream Weaver client talks to the Dream Weaver gateway, not directly to ComfyUI.

Flow:

1. Health check /health.
2. Route probe /dream-weaver/status/velocity-route-probe.
3. Resize source image to square 1024 JPEG.
4. Submit multipart request to POST /dream-weaver.
5. Poll GET /dream-weaver/status/{job_id} every 2 seconds up to 150 attempts.
6. Fetch final image from GET /dream-weaver/result/{job_id}.

Current status:

• Done: production-shaped client contract.
• Limitation: generation requires gateway and ComfyUI checkpoint readiness.

7. Android Surfaces

7.1 Android Edge Phone

Location: android-edge-phone/

Stack:

• Kotlin.
• Jetpack Compose.
• Material 3.
• Native Android navigation.
• Direct HTTP calls through VelocityEdgeBackend.

Main files:

• MainActivity.kt
• data/VelocityEdgeBackend.kt
• features/AlertsScreen.kt
• features/LeadSummaryScreen.kt
• features/CommunicationsScreen.kt
• features/NotesScreen.kt
• features/TranscriptionsScreen.kt
• features/SettingsScreen.kt

Routes/tabs:

• Alerts.
• Lead.
• Comms.
• Notes.
• Transcripts.
• Settings.

Backend integration:

• /api/auth/login
• /api/leads
• /api/mobile-edge/alerts
• /api/mobile-edge/events
• /api/mobile-edge/memory
• /api/mobile-edge/notes
• /api/mobile-edge/transcripts/{event_id}

Configuration:

• VELOCITY_BASE_URL
• VELOCITY_BEARER_TOKEN
• VELOCITY_API_EMAIL
• VELOCITY_API_PASSWORD

Current status:

• Done: real backend-facing companion surface exists.
• Partial: UI is intentionally narrow and production-edge focused.
• Left: add richer offline handling, push notifications, secure credential storage, and field-ready workflows.

7.2 Android Tablet

Location: android-tablet/

Current status:

• Build scaffold exists.
• No complete tablet feature implementation was observed during inspection.
• Left: implement tablet-specific product experience or retire scaffold if iPad remains the only tablet target.

8. Backend: Velocity Neural Core

Location: backend/
Framework: FastAPI
Primary file: backend/main.py

Core responsibilities:

• Auth and tenant user context.
• CRM, imports, leads, client graph, tasks, and opportunities.
• Mobile-edge events, memory, calendar, alerts, transcripts, and notes.
• Catalyst marketing and ad network abstraction.
• Oracle routes and canvas APIs.
• Sentinel perception/QD/session routes.
• CCTV auto-mode route family.
• Inventory property/media/import APIs.
• Communications provider and inbox APIs.
• Admin surface.
• Runtime LLM provider and batch APIs.
• Observability.

8.1 Backend Startup

backend/main.py:

• Loads .env.
• Initializes FastAPI app.
• Configures CORS from CORS_ORIGINS.
• Creates async PostgreSQL pool.
• Applies migration/bootstrap routines.
• Ensures user directory schema.
• Mounts API routers.
• Optionally serves static assets from VELOCITY_ASSET_DIR.
• Exposes /health.

Current status:

• Done: production-shaped backend composition.
• Risk: startup behavior depends on database connectivity and environment configuration.

8.2 Auth

Location: backend/auth/routes.py

Routes:

• POST /api/auth/login
• GET /api/auth/me
• GET /api/auth/users
• POST /api/auth/profile/avatar

Roles:

• ADMIN
• SALES_DIRECTOR
• SENIOR_BROKER
• JUNIOR_BROKER

Current status:

• Done: JWT auth and role/tenant-aware patterns.
• Left: ensure production secrets, token lifetimes, and refresh-token policy are hardened.

8.3 Legacy CRM and Canonical CRM

Legacy routes: backend/api/routes_crm.py
Canonical routes: backend/api/routes_crm_imports.py

Legacy CRM routes:

• /api/leads
• /api/leads/{id}
• /api/chat-logs
• /api/kanban
• /api/kanban/move
• /api/analytics/demographics
• /api/analytics/sentiment-scatter

Canonical CRM routes:

• GET/POST /api/crm/imports
• GET /api/crm/imports/{batch_id}
• PUT /api/crm/imports/{batch_id}/review-proposal
• POST /api/crm/imports/{batch_id}/commit
• GET/POST /api/crm/contacts
• GET /api/crm/contacts/{person_id}
• GET /api/crm/client-360/{person_id}
• GET/PATCH /api/crm/opportunities
• PATCH /api/crm/opportunities/{opportunity_id}
• GET/POST /api/crm/tasks
• PATCH /api/crm/tasks/{reminder_id}
• GET /api/crm/kanban
• PATCH /api/crm/leads/{lead_id}/stage
• GET /api/crm/qd/{person_id}
• GET/PATCH /api/crm/client-data
• GET /api/crm/client-data/{person_id}
• GET /api/crm/client-data/{person_id}/timeline
• POST /api/crm/client-data/{person_id}/tasks

Supported CRM task statuses:

• pending
• confirmed
• done
• snoozed
• cancelled

Current status:

• Done: robust canonical route family and legacy bridge.
• Partial: frontend surfaces do not expose every backend capability.
• Risk: legacy and canonical CRM data must be monitored for drift.

8.4 Mobile Edge

File: backend/api/routes_mobile_edge.py

Routes:

• GET/POST /api/mobile-edge/events
• GET /api/mobile-edge/memory
• POST /api/mobile-edge/imports
• POST /api/mobile-edge/notes
• GET/POST/PATCH/DELETE /api/mobile-edge/calendar
• GET/PATCH/DELETE /api/mobile-edge/calendar/{event_id}
• GET /api/mobile-edge/transcripts/{event_id}
• GET /api/mobile-edge/insights/{lead_id}
• POST /api/mobile-edge/insights/{recommendation_id}/act
• GET /api/mobile-edge/alerts
• POST /api/mobile-edge/session

Calendar statuses:

• tentative
• confirmed
• done
• cancelled

Current status:

• Done: mobile-edge backbone for field surfaces.
• Done: calendar and task behaviors used heavily by iPad.
• Left: add broader integration tests for count semantics across create, done, cancel, remove, undo, and local fallback.

8.5 Inventory Backend

File: backend/api/routes_inventory.py

Routes:

• Inventory import batch create/list/get.
• Property create/list/get/patch/archive.
• Property media create/list/delete.

Supported concepts:

• Source types: csv, json, api_push, manual.
• Property statuses: active, archived, draft, under_review.
• Media types: image, video, floorplan, brochure, 360, vr.

Current status:

• Done: backend API exists.
• Partial: WebOS inventory still needs full canonical hydration and management UI.

8.6 Catalyst Backend

File: backend/api/routes_catalyst.py
Service: backend/services/ad_network_service.py

Routes:

• GET /api/catalyst/campaigns
• POST /api/catalyst/campaigns/create
• POST /api/catalyst/creative/sync
• GET /api/catalyst/insights/realtime
• PUT /api/catalyst/budget
• PUT /api/catalyst/bid-strategy
• POST /api/catalyst/audiences/lookalike
• POST /api/catalyst/auth/meta

Current status:

• Done: route family and ad network abstraction.
• Partial: Meta Marketing API requires SDK credentials and provider setup.
• Partial: Google/provider-managed behavior can simulate data when env is not ready.

8.7 Oracle Backend

Files:

• backend/api/routes_oracle.py
• backend/api/routes_oracle_templates.py
• backend/oracle/router_v1.py

Capabilities:

• Health and data health.
• Schema catalog.
• Query execution.
• MCP tools and execution.
• Workflow preview.
• Actions and writeback.
• Canvas pages.
• Page prompts.
• Revisions.
• Forks.
• Rollback.
• Component templates.
• Persona health/rendering.
• Merge requests.
• WebSocket collaboration.

Current status:

• Done: extensive backend route family.
• Partial: dependent on data, LLM provider, and service configuration.

8.8 Sentinel and CCTV Backend

Files:

• backend/routers/sentinel.py
• backend/routers/cctv.py
• backend/routers/scenes.py
• backend/routers/videos.py

Routes:

• POST /api/sentinel/consent
• POST /api/sentinel/session/complete
• POST /api/sentinel/tag-lead
• GET /api/sentinel/qd-score/{lead_id}
• WS /api/sentinel/ws/notifications
• WS /api/sentinel/ws/perception
• POST /api/cctv/event
• POST /api/cctv/finalize-auto-mode
• POST /api/scenes/upload
• GET /api/scenes/{video_asset_id}
• GET /api/videos/marketing

Current status:

• Done: core QD/perception backend contracts.
• Partial: auto-mode lead matching requires operational validation and richer UX.

8.9 Communications Backend

File: backend/api/routes_comms.py

Routes:

• GET /api/comms/threads
• GET /api/comms/threads/{thread_id}
• GET /api/comms/threads/{thread_id}/messages
• POST /api/comms/threads/{thread_id}/messages
• POST /api/comms/threads/{thread_id}/link-person
• POST /api/comms/notes
• POST /api/comms/tasks
• GET/PATCH /api/comms/settings
• POST /api/comms/provider/test
• POST /api/comms/recordings/transcribe
• POST /api/comms/webhooks/{provider}

Providers:

• WAHA.
• Evolution.
• Mock provider.

Current status:

• Done: provider abstraction and inbox routes.
• Partial: production behavior depends on provider credentials and webhook deployment.

8.10 Admin Surface

File: backend/api/routes_admin_surface.py

Purpose:

Operational admin APIs for health, queues, installs, actions, templates, logs, and synthetic jobs.

Current status:

• Done: route family and WebOS admin page exist.
• Left: connect all operational queues/jobs to real production workflows.

8.11 Runtime LLM

File: backend/api/routes_runtime_llm.py
Service: backend/services/runtime_llm_service.py

Purpose:

Centralized LLM provider and batch execution layer.

Routes:

• Provider catalog.
• Chat.
• Batch execution.
• Batch job status.
• Batch job results.

Current status:

• Done: provider abstraction exists.
• Partial: production behavior depends on configured provider endpoints, keys, and model availability.

8.12 Observability

Files:

• backend/api/routes_observability.py
• backend/db/migrations/202604230001_observability_foundation.sql

Purpose:

Request, runtime, and platform observability foundation.

Current status:

• Done: route/migration foundation exists.
• Left: build operational dashboards and alerting around it.

9. Database and Persistence

Database layer:

• PostgreSQL.
• Async access through asyncpg.
• Schema bootstrap and migrations under backend/db.

Important schema files:

• backend/db/schema.sql
• backend/db/schema_crm_canonical.sql
• backend/db/schema_comms.sql
• backend/db/schema_addendum.sql
• backend/db/migrations/202604230001_observability_foundation.sql
• backend/db/migrations/202604260001_mobile_edge_calendar_events.sql
• backend/db/migrations/202604260002_calendar_event_done_status.sql

Major persisted domains:

• Users and roles.
• Leads intelligence.
• Canonical CRM contacts/imports/tasks/opportunities.
• Mobile-edge events, memory, notes, calendar, alerts, transcripts.
• Communications threads/messages/provider settings.
• Inventory properties/media/import batches.
• Oracle canvas pages/revisions/merge requests.
• Observability events.
• Vault assets.

Local persistence:

• WebOS: Zustand local persistence for limited global state.
• iPad: UserDefaults fallback for locally created calendar events, task status overrides, and hidden/cancelled task state.
• Android edge phone: no significant local persistence beyond runtime/config patterns observed.

Production recommendation:

All user-visible business records should be treated as backend-owned. Local persistence is acceptable for resilience and offline fallback, but not for canonical cross-device truth.

10. Dream Weaver and ComfyUI

Location: comfy_engine/

Primary gateway:

• comfy_engine/scripts/dw_gateway_v2.py

Purpose:

Dream Weaver receives a room image, target room type, and keywords, then creates a transformed/staged room render using ComfyUI workflows.

Important workflows:

• workflows/dream_weaver_restyle.json
• workflows/dreamweaver_a100_human_preservation.json
• workflows/dreamweaver_phase1_depth.json
• workflows/dreamweaver_phase2_multicontrol.json
• workflows/dreamweaver_phase3_batch.json
• workflows/catalyst_poster_qwen.json
• workflows/cinematic_wan22_14b.json

Gateway routes:

• GET /health
• GET /room-types
• POST /dream-weaver/expand
• POST /dream-weaver
• GET /dream-weaver/status/{job_id}
• GET /dream-weaver/result/{job_id}
• POST /dream-weaver/sync
• GET /dream-weaver/status/velocity-route-probe

Configuration:

• COMFYUI_URL or COMFY_URL
• COMFYUI_TLS_VERIFY
• Gateway API key via gateway_auth.py
• Preferred checkpoint/model configuration.

Health checks:

• ComfyUI /system_stats
• ComfyUI /models/checkpoints
• Dream Weaver route probe
• LLM/prompt-expansion availability

Current status:

• Done: robust gateway contract and WebOS/iPad clients.
• Partial: generation blocks when ComfyUI is offline or no compatible checkpoint is available.
• Limitation: jobs are kept in process memory. A gateway restart loses job status/result metadata unless durable storage is added.
• Risk: direct public ComfyUI route issues can produce 400 Bad Request or TLS/route errors if the payload or upstream route is misconfigured.
• Note: backend/api/routes_weaver.py is currently an empty placeholder and is not mounted by backend/main.py; the active Dream Weaver route family lives in the separate comfy_engine/scripts/dw_gateway_v2.py gateway.

Recommended production hardening:

• Add Redis/PostgreSQL-backed job store.
• Add artifact storage for generated images.
• Add deterministic model/checkpoint hydration checks.
• Add gateway-level request validation and clearer error messages for Comfy payload failures.
• Keep clients using the Dream Weaver gateway, not direct ComfyUI routes.

11. Infrastructure and Operations

Location: infrastructure/

11.1 Desi Neuron Ingress

Location: infrastructure/desineuron_ingress/

Purpose:

Stable public ingress, DNS, route sync, and tunnel management.

Important components:

• Caddy configuration.
• rathole server/client config.
• Velocity site deployment scripts.
• Comfy route sync.
• LLM route sync.
• Gitea webhook receiver.
• Home IP sync.
• GPU ComfyUI service installer.
• GPU LLM runtime installers/watchdogs.

Known operational notes from handoff:

• Stable ingress host/IP is managed through AWS/Cloudflare.
• Comfy route is intended to reach GPU ComfyUI through the ingress/tunnel layer.
• Public GPU ports should remain closed; ingress should mediate access.

Current status:

• Done: substantial route/deploy automation.
• Risk: route drift, DNS mismatch, or tunnel failure can break WebOS/iPad Dream Weaver even if client code is correct.

11.2 Ops Control Plane

Location: infrastructure/ops_control_plane/

Purpose:

Server-rendered operational control plane for machine profiles, AWS market snapshots, routes, jobs, sessions, model hydration, lifecycle actions, route binding, and audit trails.

Main file:

• infrastructure/ops_control_plane/app/ops_control_plane/main.py

Current status:

• Done: control plane backend/templates exist.
• Left: production deployment, access control review, and operator runbook validation.

11.3 AWS Scale

Location: infrastructure/aws_scale/

Purpose:

Terraform/configuration for agent and rendering nodes, plus Tailscale setup.

Current status:

• Partial: infrastructure-as-code assets exist.
• Left: validate against current AWS account and desired production topology.

11.4 Blackbox Local

Location: infrastructure/blackbox_local/

Purpose:

Local Docker/GPU environment helpers.

Current status:

• Partial: useful for local experimentation and environment setup.

12. Testing Coverage

Backend tests:

• Auth tenant contract.
• Canonical CRM auth and tenant scoping.
• Catalyst routes.
• CRM routes and WebSocket.
• Dream Weaver gateway auth.
• Legacy CRM bridge and write bridge.
• Migrations and observability.
• NemoClaw runtime and QD scoring.
• Oracle routes and Oracle service tests.
• Surface route tenant scoping.
• Vault notification flow.

WebOS tests:

• Notification center Playwright spec.
• Sentinel live session Playwright spec.

Current status:

• Good backend test foundation.
• Limited frontend e2e coverage relative to the number of production surfaces.
• No exhaustive cross-surface test matrix observed.

Recommended test expansion:

• Calendar create/update/done/cancel/remove/undo count contracts.
• Dream Weaver health/generate/error states in WebOS and iPad.
• CRM import review/commit full flow.
• Comms provider webhook and inbox sync.
• Inventory property/media creation and frontend hydration.
• Catalyst marketing provider failure states.
• Oracle prompt-to-canvas-to-writeback flow.
• Sentinel assigned and auto mode end-to-end.

13. Feature Status Matrix

Area	Status	Notes
WebOS shell/auth	Done	Login/session/admin gating implemented
WebOS Dashboard	Partial	UI done; some metric sources need canonical backend contracts
WebOS CRM	Partial	Strong read UX; full CRUD/import review still needs polish
WebOS Communications	Partial	Backend routes exist; provider readiness required
WebOS Oracle	Partial	Rich UI/backend; depends on LLM/data readiness
WebOS Sentinel	Partial	Live flow exists; auto mode needs validation
WebOS Inventory	Partial	Rich UI; canonical backend hydration incomplete
WebOS Catalyst Studio	Partial	UI exists; render action not fully production-wired
WebOS Catalyst Marketing	Partial	Backend-backed; provider credentials required
WebOS Dream Weaver	Partial/Ready-gated	Implemented; blocked by gateway/Comfy/checkpoint availability
WebOS Settings	Partial	Many controls exist; some settings local-only
WebOS Admin	Partial	Admin page/routes exist; operational data needs deployment
iPad Dashboard	Done/Partial	Native and app-store backed; metric parity should be validated
iPad Clients	Done/Partial	Live data patterns exist
iPad Imports	Partial	Import flows exist; review UX should be validated
iPad Communications	Partial	Module exists; provider readiness required
iPad Calendar	Done	Strong backend + local fallback behavior
iPad Oracle	Partial	Module exists; backend/LLM dependent
iPad Sentinel	Partial	Module exists; parity needs validation
iPad Inventory	Partial	Advanced native features; data/media readiness required
iPad Dream Weaver	Partial/Ready-gated	Client complete; Comfy/gateway dependent
Android Edge Phone	Partial	Live backend companion exists; narrow field scope
Android Tablet	Not complete	Scaffold only
Backend auth	Done	Tenant/role-aware JWT
Backend CRM	Done/Partial	Strong route family; frontend parity incomplete
Backend mobile-edge	Done	Used by iPad/Android
Backend Catalyst	Partial	Provider credentials required
Backend Oracle	Partial	Rich route family; LLM/data dependent
Backend Sentinel	Partial	Route family present; operational validation needed
Backend Inventory	Partial	API exists; frontend data contract incomplete
Backend Comms	Partial	Provider integration required
Dream Weaver gateway	Partial/Ready-gated	Route contract complete; durable jobs/checkpoint readiness needed
Infrastructure	Partial	Strong tooling; production validation required

14. Known Limitations and Risks

1. Dream Weaver depends on ComfyUI availability and checkpoint hydration. If ComfyUI is offline or /models/checkpoints is empty, generation should remain disabled.
2. Dream Weaver gateway uses in-memory job state. Generated result tracking is not durable across gateway restarts.
3. WebOS has several sophisticated prototype surfaces that are not fully backend-persistent yet, especially Catalyst Studio, War Room settings, and parts of Inventory.
4. WebOS and iPad metric definitions can drift if each surface calculates counts differently.
5. Legacy CRM and canonical CRM coexist. This is manageable, but drift prevention and bridge tests must remain a priority.
6. Communications production readiness depends on external provider credentials and webhook stability.
7. Catalyst production readiness depends on Meta/Google credentials, SDK behavior, and ad account permissions.
8. Sentinel auto-mode requires stronger operational validation before it can be considered production-ready.
9. Android tablet is not implemented as a real feature surface.
10. Frontend e2e coverage is small compared with the breadth of the application.
11. Local fallback behavior is useful, but business-critical records must be synchronized to backend persistence.
12. Infrastructure route failures can appear as application failures unless health panels clearly distinguish gateway, route, Comfy, checkpoint, and payload errors.

15. Recommended Next Work

Priority 1: Production correctness

• Define canonical metric contracts for Today, Pending Tasks, Confirmed, Done, Cancelled, and Removed across backend, WebOS, and iPad.
• Add API contract tests for task/calendar counts and status transitions.
• Keep all business records backend-owned and use local persistence only as a recovery layer.

Priority 2: Dream Weaver hardening

• Add durable job state to Dream Weaver gateway.
• Add artifact storage for generated results.
• Add model/checkpoint hydration runbook and automated health warning.
• Improve gateway error normalization for Comfy 400 Bad Request, missing checkpoint, bad image, and route/TLS failures.

Priority 3: WebOS backend parity

• Complete CRM import review/commit UI.
• Add full contact/opportunity/task CRUD where backend already supports it.
• Connect Inventory to canonical property/media APIs.
• Wire Catalyst Studio render action to a real backend/gateway flow.
• Persist War Room/provider settings securely.

Priority 4: Operational readiness

• Deploy and validate Ops Control Plane access.
• Add production observability dashboards.
• Add health checks for backend, Postgres, ComfyUI, Dream Weaver gateway, provider credentials, and external route sync.
• Add runbooks for route failures, Comfy checkpoint hydration, provider outages, and database migrations.

Priority 5: Mobile parity

• Validate iPad/WebOS feature parity for CRM, calendar, Dream Weaver, and inventory.
• Add secure credential storage and push notifications to Android edge phone.
• Decide whether Android tablet is a product target and either implement or retire the scaffold.

16. Development Runbook

16.1 WebOS

cd app
npm install
npm run dev
npm run build
npm run lint
npm run test:e2e

Typical local URL:

http://127.0.0.1:5173

Important environment variables:

• VITE_API_URL
• VITE_DREAM_WEAVER_URL
• VITE_DREAM_WEAVER_API_KEY

16.2 Backend

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

Important environment variables:

• DATABASE_URL
• JWT_SECRET
• CORS_ORIGINS
• Meta/Google provider credentials where applicable.
• Comms provider configuration where applicable.
• Runtime LLM provider configuration where applicable.

Tests:

pytest backend/tests

16.3 Dream Weaver Gateway

Example local run:

COMFYUI_URL=http://127.0.0.1:8188 python3 comfy_engine/scripts/dw_gateway_v2.py

Example remote/ingress run:

COMFYUI_URL=https://comfy.desineuron.in COMFYUI_TLS_VERIFY=false python3 comfy_engine/scripts/dw_gateway_v2.py

Required health conditions:

• Gateway /health is online.
• Dream Weaver route probe is mounted.
• ComfyUI is reachable.
• Compatible checkpoint exists.
• API key matches clients when auth is enabled.

16.4 iPad

Open the Xcode project under:

iOS/velocity-ipad/

Configure:

• Backend base URL.
• Auth/session token or credentials.
• Dream Weaver gateway URL/API key.

16.5 Android Edge Phone

Open:

android-edge-phone/

Configure Gradle properties:

• VELOCITY_BASE_URL
• VELOCITY_BEARER_TOKEN
• or VELOCITY_API_EMAIL and VELOCITY_API_PASSWORD

17. Definition of Done for Production Readiness

A module should be considered production-ready only when all of the following are true:

• The primary UX is complete and handles loading, success, empty, validation, and failure states.
• All business data is persisted in the backend or an explicitly approved durable system.
• Local fallback behavior does not become the hidden source of truth.
• Counts and badges are derived from a documented backend contract.
• Auth, tenant scope, and role permissions are enforced.
• External provider failures are visible and actionable.
• End-to-end tests cover the main workflow.
• Operational health checks clearly identify which dependency is failing.
• The runbook explains how to start, verify, and recover the module.

18. Bottom Line

Project Velocity is already much more than a prototype. It has a serious multi-surface architecture and a broad backend foundation. The main work left is not inventing the product from scratch. It is consolidating the existing implementation into durable, tested, backend-owned workflows, then closing the final gaps where rich UI surfaces still outrun persistence, provider configuration, or operational readiness.

This document should be treated as the current single source of truth until the next major codebase review updates it.