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
2. Application Overview
3. Technology Stack
4. Architecture
5. Project Structure
6. Core Modules
7. State Management
8. Design System
9. Development Guidelines
10. 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

┌─────────────────────────────────────────────────────────────┐
│                       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.

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

---

Project Structure

Directory Layout

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()).

// 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).