sagnik/Project_Velocity
2
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c93e317416af3e20645094d3337305512a5e42a
Project_Velocity/.Agent Context/Sayan's Docs/Project Velocity Software SOT 1.md
Sayan Datta 6c93e31741
All checks were successful
Production Readiness / backend-contracts (pull_request) Successful in 3m19s
Details
Production Readiness / webos-typecheck (pull_request) Successful in 2m38s
Details
Production Readiness / ipad-parse (pull_request) Successful in 1m44s
Details
feat: Ipad app production readiness, Colony orchestration, Social posting
2026-05-03 18:28:04 +05:30

1624 lines
48 KiB
Markdown
Raw Blame History

# 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:
```text
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
```bash
cd app
npm install
npm run dev
npm run build
npm run lint
npm run test:e2e
```
Typical local URL:
```text
http://127.0.0.1:5173
```
Important environment variables:
- `VITE_API_URL`
- `VITE_DREAM_WEAVER_URL`
- `VITE_DREAM_WEAVER_API_KEY`
### 16.2 Backend
```bash
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:
```bash
pytest backend/tests
```
### 16.3 Dream Weaver Gateway
Example local run:
```bash
COMFYUI_URL=http://127.0.0.1:8188 python3 comfy_engine/scripts/dw_gateway_v2.py
```
Example remote/ingress run:
```bash
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:
```text
iOS/velocity-ipad/
```
Configure:
- Backend base URL.
- Auth/session token or credentials.
- Dream Weaver gateway URL/API key.
### 16.5 Android Edge Phone
Open:
```text
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.
Reference in New Issue View Git Blame Copy Permalink