Project_Velocity/.Agent Context/velocity_ios_bible.md

# Velocity iOS App - Technical Bible

**Document Version:** 1.0  
**Last Updated:** 2026-03-07  
**Application Version:** 1.1.0

---

## Table of Contents

1. [Executive Summary](#executive-summary)
2. [Application Overview](#application-overview)
3. [Technology Stack](#technology-stack)
4. [Architecture](#architecture)
5. [Project Structure](#project-structure)
6. [Core Modules](#core-modules)
7. [State Management](#state-management)
8. [Design System](#design-system)
9. [Development Guidelines](#development-guidelines)
10. [API Integration Points](#api-integration-points)

---

## Executive Summary

**Velocity iOS** is the native mobile counterpart of the Velocity premium real estate sales enablement platform. Built natively for Apple devices using SwiftUI, it brings the luxury property showcase and experience center ecosystems directly into the hands of sales teams on the showroom floor. The application features seamless integrations with AI-powered lead management (Oracle), biometric visitor tracking (Sentinel), and real-time inventory management.

**Purpose:** Provide sales teams with portable, native, intelligent insights and immersive property presentations with uncompromising performance and battery efficiency.

**Target Users:** Sales Directors, Real Estate Agents, Property Managers on the floor.

---

## Application Overview

### Key Features

1. **Dashboard** - Real-time metrics (Visitors, Revenue, AI Jobs, Listings), sentiment analysis gauge, system health monitoring, and a quick live AI Chat Widget.
2. **The Oracle** - AI-powered lead management interface to handle WhatsApp, web, and walk-in leads.
3. **The Sentinel** - Biometric visitor tracking interface, visualizing Live visitor IDs, emotion, confidence, dwell time, and zones.
4. **Inventory** - Real-time unit availability tracking, including augmented reality overlays (`ARSunOverlayView`).
5. **Settings** - App configurations and connectivity testing.

### User Flow

```
Launch (VelocityApp) -> ContentView (Entry Hub) -> Feature Tabs/Navigation -> Native Views (Dashboard, Oracle, Sentinel, etc.)
```

---

## Technology Stack

### Core Frameworks
- **Swift** - Primary programming language.
- **SwiftUI** - Declarative UI framework for building the entire interface.
- **Combine / Observation** (`@Observable`) - Reactive programming for robust state management.

### Networking & Data
- **Alamofire** (via `ComfyClient.swift`) - Elegant HTTP networking for handling requests (e.g. Dream Weaver AI image generation).

### UI & Animations
- **SwiftUI Animation** - Native transitions (`.easeInOut`, `.spring()`, `.numericText()`).
- **Glassmorphism natively** - via custom modifiers and blurs (`GlassCard`, `GlassBlurView`).

---

## Architecture

### Application Architecture

```text
┌─────────────────────────────────────────────────────────────┐
│                       VelocityApp.swift                     │
│               (App Entry & WindowGroup Setup)               │
└─────────────────────────────────┬───────────────────────────┘
                                  │
┌─────────────────────────────────┴───────────────────────────┐
│                        ContentView.swift                    │
│                 (Main App Structure / Tab View)             │
└──────┬────────────────────┬──────────────────────┬──────────┘
       │                    │                      │
┌──────┴──────┐      ┌──────┴──────┐        ┌──────┴──────┐
│  Dashboard  │      │   Oracle    │        │  Sentinel   │
│   Module    │      │   Module    │        │   Module    │
└─────────────┘      └─────────────┘        └─────────────┘
```

### State Architecture
A centralized `AppStore` leverages the `@Observable` macro to power the state of the app across different modules asynchronously.

```text
┌────────────────────────────────────────────────┐
│               AppStore.swift (@Observable)     │
├────────────────────────────────────────────────┤
│  Metrics (DashboardMetrics)                    │
│  Visitors (Sentinel array)                     │
│  Alerts (isAlertActive, alertMessage)          │
│  Leads & Messages (Oracle data)                │
└──────────────────────┬─────────────────────────┘
                       │
             ┌─────────┴──────────┐
             │ UI Subscriptions   │
             │ (Environment/State)│
             └────────────────────┘
```

---

## Project Structure

### Directory Layout

```text
iOS/
├── App/                     # App Lifecycle
│   ├── ContentView.swift    # Main App Tab/Navigation Hub
│   └── VelocityApp.swift    # @main Entry Point
├── Core/                    # Shared infrastructure
│   ├── Math/
│   │   └── SunMath.swift    # Calculation utilities for AR/Environment
│   ├── Networking/
│   │   └── ComfyClient.swift# Alamofire client (AI integrations)
│   ├── State/
│   │   └── AppStore.swift   # Single source of truth state manager
│   └── UI/
│   │   ├── GlassBlurView.swift # Native blur implementations
│   │   └── VelocityTheme.swift # Design system tokens
└── Features/                # Feature-specific modules
    ├── Dashboard/
    │   └── DashboardView.swift # Analytics, KPIs, Sentiment Gauge
    ├── Inventory/
    │   ├── ARSunOverlayView.swift # AR overlay for property sun paths
    │   └── InventoryView.swift
    ├── Oracle/
    │   └── OracleView.swift # Lead progression and AI chat interface
    ├── Sentinel/
    │   └── SentinelView.swift # Visitor facial & emotion analysis
    └── Settings/
        └── SettingsView.swift # App configuration
```

---

## Core Modules

### 1. Dashboard (`DashboardView.swift`)
**Purpose:** Executive overview matching the WebOS counterpart with native fluidity.
**Components:**
- **LiveKPICard**: Displays `Visitors`, `Revenue`, `AI Jobs`, and `Listings` with pulse animations.
- **Sentiment Gauge**: A dynamic, animated thermometer evaluating the overall showroom vibe.
- **System Health Panel**: Monitors underlying CPU/GPU/Memory configurations.
- **AI Chat Widget**: Embedded, fast-access AI query terminal with typing indicators and conversational memory.

### 2. Apps & AI Integration (`ComfyClient.swift` & Oracles)
The iOS app natively implements calls to standard HTTP backends and advanced AI generation services using an `Alamofire` `Session` directly connecting to high-GPU instances for rapid image synthesis (`DreamWeaverRequest`).

---

## State Management

### Zustand to AppStore Mapping
The iOS app natively replicates the WebOS `Zustand` state mechanism heavily through `AppStore.swift`.

- **Live Ticker:** Contains a background publisher running every 5 seconds that jitter-updates visitors, sentiment, and raises mock backend alerts.
- **Models:**
  - `Visitor`: Contains `id`, `faceId`, `sentiment`, `confidence`, `zone`.
  - `Lead`: Categorizes lead paths (Walk-in, Website, WhatsApp), Qualification (Whale, Potential), Budget.
  - `ChatMessage` & `DashboardMetrics`: Shared data schemas for AI interactions and KPIs.

---

## Design System

**Location:** `Core/UI/VelocityTheme.swift`

### Color Palette
Precisely mirrors the web dashboard's high-contrast, premium dark mode:
- **Backgrounds**: True black `(0, 0, 0)` with elevated surfaces (`#131418`, `#22262e`).
- **Foregrounds**: Off-white for max readability, subtle grays for muted elements.
- **Accent**: `VelocityTheme.accent` `(0.231, 0.510, 0.965)` (Blue)
- **Semantic Status**: Matches SwiftUI `Color` blocks (`success`, `warning`, `danger$).

### Native Glassmorphism
Using native `VisualEffectView` or styled semi-transparent blocks wrapped in `.modifier(GlassCard())`.
```swift
// Implementation
.background(
    RoundedRectangle(cornerRadius: 16)
        .fill(Color(red: 0.031, green: 0.039, blue: 0.071).opacity(0.82))
        .overlay(RoundedRectangle(cornerRadius: 16).stroke(VelocityTheme.borderAccent, lineWidth: 1))
        .shadow(color: .black.opacity(0.55), radius: 16, y: 4)
)
```

---

## Development Guidelines

**UI Paradigms:**
- Leverage `ZStack` and `GeometryReader` for scale-dependent UI components like gauges and progress bars.
- Add subtle animations using `.animation(.easeInOut(duration: 0.4), value: ...)` to make data updates feel organic.
- Restrict logic calculations out of the `View` body, moving them to extensions, external math engines (`SunMath.swift`), or the `AppStore`.

---

## API Integration Points

**ComfyClient / Dream Weaver:**
- Core generation client utilizing `.post` to `http://192.168.x.x:8000/dream-weaver`.
- Automates formatting to Base64 formats for sending payloads to AI models and decoding the respective `output_base64` image back to a `UIImage`.

*(Note: Data sources like leads and visitors are currently heavily maintained via the native `AppStore` state but conform to general structures mapping to `/api/leads` and `/api/visitors` on the production backends).*