# Velocity Web App - Technical Bible

**Document Version:** 1.0  
**Last Updated:** 2026-02-18  
**Application Version:** 2.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. [Component Library](#component-library)
10. [Development Guidelines](#development-guidelines)
11. [Build & Deployment](#build--deployment)
12. [API Integration Points](#api-integration-points)

---

## Executive Summary

**Velocity** is a premium real estate sales enablement platform built for luxury property showcases and experience centers. The application integrates AI-powered lead management (Oracle), biometric visitor tracking (Sentinel), real-time inventory management, and comprehensive analytics dashboards to create an end-to-end sales enablement ecosystem.

**Purpose:** Empower sales teams with intelligent insights, automated lead qualification, sentiment analysis, and immersive property presentations.

**Target Users:** Sales Directors, Real Estate Agents, Property Managers

---

## Application Overview

### Key Features

1. **Dashboard** - Real-time metrics, lead velocity charts, sentiment analysis, system health monitoring
2. **The Oracle** - AI-powered lead management with automated qualification and intelligent chat
3. **The Sentinel** - Biometric visitor tracking with facial recognition and sentiment analysis
4. **Inventory** - Unit availability tracking with advanced filters and status management
5. **Settings** - System configuration and user preferences

### User Flow

```
Login Screen (FaceID Auth) → Dashboard → Module Navigation (Sidebar) → Feature Interactions
```

---

## Technology Stack

### Frontend Framework
- **React** `19.2.0` - UI library with latest concurrent features
- **TypeScript** `5.9.3` - Static typing and enhanced DX
- **Vite** `7.2.4` - Fast build tool with HMR

### State Management
- **Zustand** `5.0.11` - Lightweight state management with persistence
- **Zustand Persist Middleware** - LocalStorage persistence for auth/navigation state

### UI Framework
- **Tailwind CSS** `3.4.19` - Utility-first styling
- **shadcn/ui** - 40+ pre-built, accessible components
- **Radix UI** - Headless component primitives for accessibility
- **Framer Motion** `12.34.1` - Advanced animations and transitions

### Data Visualization
- **Recharts** `2.15.4` - Composable charting library

### Form Management
- **React Hook Form** `7.70.0` - Performant form handling
- **Zod** `4.3.5` - Schema validation

### Icons & Assets
- **Lucide React** `0.562.0` - Modern icon library

### Utilities
- **date-fns** `4.1.0` - Date manipulation
- **clsx** / **tailwind-merge** - Conditional className handling
- **class-variance-authority** - Component variant management

---

## Architecture

### Application Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    App.tsx (Root)                       │
│              ┌──────────────────────────┐               │
│              │  Authentication Guard    │               │
│              └──────────┬───────────────┘               │
│                         │                                │
│         ┌───────────────┴────────────────┐              │
│         │                                 │              │
│   LoginScreen                        MainLayout         │
│                                           │              │
│                          ┌────────────────┼────────────┐│
│                          │                │            ││
│                      Sidebar         Module Router     ││
│                                           │            ││
│                          ┌────────────────┴──────┐    ││
│                          │                        │    ││
│                     Dashboard        Oracle/Sentinel/ ││
│                                      Inventory/etc     ││
└─────────────────────────────────────────────────────────┘
```

### State Architecture

```
┌────────────────────────────────────────────────┐
│         Zustand Store (useStore.ts)            │
├────────────────────────────────────────────────┤
│  AuthState       │ Navigation   │ Oracle       │
│  SentinelState   │ Dashboard    │ Inventory    │
│  SystemState     │              │              │
└────────────────────────────────────────────────┘
        │
        ├── LocalStorage Persistence (auth, activeModule)
        └── Component Subscriptions (selective)
```

### Component Hierarchy

```
src/
├── components/
│   ├── layout/          # Layout components
│   │   ├── LoginScreen  # Authentication UI
│   │   └── Sidebar      # Navigation sidebar
│   ├── modules/         # Feature modules
│   │   ├── Dashboard    # Analytics dashboard
│   │   ├── Oracle       # Lead management
│   │   ├── Sentinel     # Visitor tracking
│   │   ├── Inventory    # Unit management
│   │   └── Settings     # Configuration
│   └── ui/              # shadcn/ui components (40+)
├── store/               # Zustand state
├── types/               # TypeScript definitions
├── lib/                 # Utilities
└── hooks/               # Custom React hooks
```

---

## Project Structure

### Directory Layout

```
app/
├── dist/                    # Production build output
├── src/
│   ├── components/
│   │   ├── layout/
│   │   │   ├── LoginScreen.tsx (8KB)  # FaceID auth screen
│   │   │   └── Sidebar.tsx (5KB)      # App navigation
│   │   ├── modules/
│   │   │   ├── Dashboard.tsx (15KB)   # Analytics dashboard
│   │   │   ├── Oracle.tsx (18KB)      # AI chat + lead mgmt
│   │   │   ├── Sentinel.tsx (19KB)    # Biometric tracking
│   │   │   ├── Inventory.tsx (18KB)   # Unit management
│   │   │   └── Settings.tsx (16KB)    # App config
│   │   └── ui/                        # 40+ shadcn components
│   ├── hooks/
│   │   └── use-mobile.ts              # Responsive breakpoint hook
│   ├── lib/
│   │   └── utils.ts                   # cn() helper
│   ├── store/
│   │   └── useStore.ts (10KB)         # Zustand state
│   ├── types/
│   │   └── index.ts (2KB)             # Type definitions
│   ├── App.tsx (4KB)                  # Root component
│   ├── App.css                        # Component styles
│   ├── index.css (5KB)                # Global styles + utilities
│   └── main.tsx                       # Entry point
├── index.html                         # HTML template
├── package.json                       # Dependencies
├── tailwind.config.js (5KB)          # Theme config
├── tsconfig.json                      # TS config
├── vite.config.ts                     # Vite config
└── components.json                    # shadcn config
```

### Configuration Files

| File | Purpose |
|------|---------|
| `vite.config.ts` | Build tool configuration, React plugin setup |
| `tailwind.config.js` | Theme customization, custom animations, velocity colors |
| `tsconfig.json` | TypeScript compiler options |
| `tsconfig.app.json` | App-specific TS config |
| `tsconfig.node.json` | Node environment TS config |
| `components.json` | shadcn/ui component installation config |
| `postcss.config.js` | PostCSS plugins (Tailwind) |
| `eslint.config.js` | Linting rules |

---

## Core Modules

### 1. Dashboard

**Purpose:** Real-time analytics and system monitoring

**Components:**
- **ActiveVisitorsWidget** - Live visitor count with pulse animation
- **TodayLeadsWidget** - Daily lead generation metrics
- **ConversionRateWidget** - Lead-to-sale conversion tracking
- **SentimentGauge** - Showroom sentiment thermometer (0-100%)
- **LeadVelocityChart** - Time-series lead generation graph
- **SystemHealth** - CPU/GPU/Memory/Temperature gauges
- **RecentActivity** - Activity feed with emoji icons

**Data Sources:**
- `useStore().metrics` - Dashboard metrics
- `useStore().velocityData` - Chart data

**Key Features:**
- Bento grid layout (4-column responsive grid)
- Framer Motion staggered animations
- Recharts area charts with gradients
- Real-time pulse indicators

---

### 2. Oracle (AI Lead Management)

**Purpose:** Intelligent lead qualification and automated conversations

**Components:**
- Lead sidebar with qualification badges (Whale/Potential/Tire Kicker)
- AI chat interface with thinking states
- Lead status pipeline (New → Engaged → Qualified → Hot → Closed)
- Unread message indicators
- Source badges (WhatsApp/Website/Walk-in)

**Data Sources:**
- `useStore().leads` - Lead database
- `useStore().messages` - Chat history per lead
- `useStore().activeLeadId` - Current conversation

**Key Features:**
- AI message generation with simulated thinking state
- Lead auto-qualification scoring
- Budget and interest tracking
- Last active timestamps
- Glassmorphic chat bubbles

---

### 3. Sentinel (Biometric Tracking)

**Purpose:** Facial recognition and sentiment analysis

**Components:**
- Live visitor grid with face IDs
- Sentiment visualization (Excited/Interested/Neutral/Confused/Disinterested)
- Zone-based tracking
- Dwell time monitoring
- Confidence scores
- Alert system for negative sentiment

**Data Sources:**
- `useStore().visitors` - Active visitor tracking
- `useStore().isAlertActive` - Alert state
- `useStore().alertMessage` - Alert content

**Key Features:**
- Real-time FaceID cards with sentiment pills
- Zone heatmaps (future enhancement)
- Automated alert triggers (<50% sentiment)
- Visitor remove capability
- Confidence percentage indicators

---

### 4. Inventory

**Purpose:** Real-time unit availability tracking

**Components:**
- Unit cards with status badges
- Floor plan visualization (future)
- Filter bar (All/Available/Reserved/Sold/Hold)
- Unit details (area, price, view, floor)
- Status management dropdown

**Data Sources:**
- `useStore().units` - Unit database
- `useStore().filterStatus` - Active filter
- `useStore().selectedUnitId` - Selected unit

**Unit Types:**
- Studio
- 1BR, 2BR, 3BR
- Penthouse

**Status States:**
```typescript
'available' | 'reserved' | 'sold' | 'hold'
```

---

### 5. Settings

**Purpose:** System configuration and user preferences

**Sections:**
- Theme settings
- Notification preferences
- System diagnostics
- User profile management
- Data sync options

---

## State Management

### Zustand Store Architecture

**Location:** `src/store/useStore.ts`

### Store Slices

#### AuthState
```typescript
{
  isAuthenticated: boolean
  user: User | null
  login: (user: User) => void
  logout: () => void
}
```

#### NavigationState
```typescript
{
  activeModule: ModuleId
  sidebarExpanded: boolean
  setActiveModule: (module: ModuleId) => void
  toggleSidebar: () => void
  setSidebarExpanded: (expanded: boolean) => void
}
```

#### OracleState
```typescript
{
  leads: Lead[]
  activeLeadId: string | null
  messages: Record<string, ChatMessage[]>
  isOracleThinking: boolean
  setActiveLead: (leadId: string | null) => void
  addMessage: (leadId: string, message: ChatMessage) => void
  setOracleThinking: (thinking: boolean) => void
  markLeadAsRead: (leadId: string) => void
}
```

#### SentinelState
```typescript
{
  visitors: Visitor[]
  isAlertActive: boolean
  alertMessage: string
  addVisitor: (visitor: Visitor) => void
  removeVisitor: (visitorId: string) => void
  triggerAlert: (message: string) => void
  clearAlert: () => void
}
```

#### DashboardState
```typescript
{
  metrics: DashboardMetrics
  velocityData: LeadVelocityData[]
  updateMetrics: (metrics: Partial<DashboardMetrics>) => void
  addVelocityDataPoint: (data: LeadVelocityData) => void
}
```

#### InventoryState
```typescript
{
  units: Unit[]
  selectedUnitId: string | null
  filterStatus: Unit['status'] | 'all'
  setSelectedUnit: (unitId: string | null) => void
  setFilterStatus: (status: Unit['status'] | 'all') => void
}
```

#### SystemState
```typescript
{
  status: SystemStatus
  updateStatus: (status: Partial<SystemStatus>) => void
}
```

### Persistence

**Storage Key:** `velocity-webos-storage`

**Persisted State:**
- `isAuthenticated`
- `user`
- `activeModule`

All other state is session-based.

---

## Design System

### Color Palette

#### Velocity Brand Colors
```javascript
velocity: {
  black: '#0a0a0a',    // Primary background
  dark: '#111111',     // Secondary background
  panel: '#151515',    // Panel background
  blue: '#3b82f6',     // Primary action
  cyan: '#06b6d4',     // Secondary action
  amber: '#f59e0b',    // Warning/attention
  green: '#22c55e',    // Success/positive
  red: '#ef4444',      // Error/negative
}
```

#### Semantic Colors (HSL)
- **Background:** `0 0% 4%` (near-black)
- **Foreground:** `0 0% 98%` (near-white)
- **Primary:** `210 100% 56%` (blue)
- **Border:** `0 0% 18%` (subtle gray)
- **Muted:** `0 0% 15%` (disabled states)

### Typography

**Font Stack:**
```css
-apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Inter', 'Segoe UI', sans-serif
```

**Letter Spacing:** `-0.01em` (tight, premium feel)

**Font Sizes:**
- Display: `text-4xl` (36px)
- Heading: `text-xl` (20px)
- Body: `text-sm` (14px)
- Caption: `text-xs` (12px)

### Spacing

**Border Radius:**
- `xs`: `calc(var(--radius) - 6px)`
- `sm`: `calc(var(--radius) - 4px)`
- `md`: `calc(var(--radius) - 2px)`
- `lg`: `var(--radius)` (0.75rem / 12px)
- `xl`: `calc(var(--radius) + 4px)`
- `2xl`: `1rem` (16px)
- `3xl`: `1.5rem` (24px)

**Default Radius:** `0.75rem` (12px)

### Glassmorphism

#### Utility Classes
```css
.glass                /* Subtle glass effect */
.glass-strong         /* Bold glass effect */
.glass-panel          /* Panel with blur */
.glass-card           /* Card with gradient + blur */
```

#### Implementation
```css
.glass-panel {
  background: rgba(255, 255, 255, 0.03);
  backdrop-filter: blur(24px);
  border: 1px solid rgba(255, 255, 255, 0.08);
  border-radius: 1rem;
}
```

### Shadows

**Glass Shadow:** `0 8px 32px rgba(0, 0, 0, 0.4)`

**Glow Effects:**
- Blue: `0 0 40px rgba(59, 130, 246, 0.3)`
- Amber: `0 0 40px rgba(245, 158, 11, 0.3)`
- Green: `0 0 20px rgba(34, 197, 94, 0.4)`

### Animations

#### Keyframes
- `accordion-down/up` - Radix accordion
- `shimmer` - Loading shimmer effect
- `pulse-glow` - Pulsing glow animation
- `slide-in/up` - Entry animations
- `fade-in` - Opacity fade
- `scale-in` - Scale + fade
- `float` - Floating hover effect
- `scan` - Scanning line effect
- `faceid-pulse` - FaceID ring pulse

#### Timing Functions
- **Apple:** `cubic-bezier(0.4, 0.0, 0.2, 1)` - Standard easing
- **Bounce:** `cubic-bezier(0.34, 1.56, 0.64, 1)` - Spring bounce

### Status Indicators

**Sentiment Pills:**
```css
.sentiment-excited    /* Green */
.sentiment-confused   /* Amber */
.sentiment-neutral    /* Gray */
```

**Status Pulse:**
```css
.status-pulse         /* Animated pulse dot */
```

---

## Component Library

### shadcn/ui Components (40+)

**Navigation:**
- Sidebar, Navigation Menu, Menubar, Breadcrumb, Pagination

**Layout:**
- Card, Separator, Scroll Area, Resizable, Aspect Ratio, Sheet

**Forms:**
- Input, Textarea, Select, Checkbox, Radio Group, Switch, Slider, Calendar, Date Picker, Input OTP

**Feedback:**
- Alert, Alert Dialog, Dialog, Drawer, Toast (Sonner), Tooltip, Hover Card, Popover, Progress, Skeleton, Spinner

**Data Display:**
- Table, Badge, Avatar, Chart, Carousel, Accordion, Collapsible, Tabs, Toggle Group

**Actions:**
- Button, Button Group, Dropdown Menu, Context Menu, Command (⌘K)

**Utilities:**
- Form (React Hook Form), Field, Label, Empty, Item, KBD

---

## Development Guidelines

### Code Style

**Component Structure:**
```typescript
// 1. Imports
import { motion } from 'framer-motion';
import { Icon } from 'lucide-react';
import { useStore } from '@/store/useStore';

// 2. Types/Interfaces
interface WidgetProps {
  children: React.ReactNode;
  className?: string;
}

// 3. Component
export function Widget({ children, className }: WidgetProps) {
  const store = useStore();
  
  return (
    <motion.div className={cn('glass-card', className)}>
      {children}
    </motion.div>
  );
}
```

**Naming Conventions:**
- Components: `PascalCase` (e.g., `Dashboard.tsx`)
- Hooks: `camelCase` with `use` prefix (e.g., `useMobile.ts`)
- Types: `PascalCase` (e.g., `ModuleId`)
- Utilities: `camelCase` (e.g., `cn()`)

**Path Aliases:**
- `@/*` → `src/*`

### Animation Guidelines

**Entry Animations:**
```typescript
initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.3, ease: [0.4, 0, 0.2, 1] }}
```

**Stagger Delays:** Increment by `0.1s` for sequential animations

**Spring Animations:**
```typescript
transition={{ 
  type: 'spring', 
  stiffness: 300, 
  damping: 30,
  mass: 0.8 
}}
```

### State Management Patterns

**Selective Subscriptions:**
```typescript
const activeModule = useStore((state) => state.activeModule);
```

**Batch Updates:**
```typescript
set((state) => ({
  ...state,
  multiple: updates,
}));
```

---

## Build & Deployment

### Scripts

```bash
npm run dev      # Start dev server (localhost:5173)
npm run build    # TypeScript check + Vite build
npm run lint     # ESLint check
npm run preview  # Preview production build
```

### Build Output

**Directory:** `dist/`

**Assets:**
- `index.html` - Entry point
- `assets/index-[hash].js` - Bundled JavaScript
- `assets/index-[hash].css` - Bundled CSS

### Environment Variables

Create `.env` file:
```env
VITE_API_URL=https://api.velocity.com
VITE_FACEID_KEY=your_key_here
VITE_ORACLE_AI_KEY=your_key_here
```

Access in code:
```typescript
const apiUrl = import.meta.env.VITE_API_URL;
```

---

## API Integration Points

### Expected Backend Endpoints

**Authentication:**
```
POST /api/auth/faceid
POST /api/auth/logout
GET  /api/auth/me
```

**Leads (Oracle):**
```
GET    /api/leads
GET    /api/leads/:id
POST   /api/leads
PATCH  /api/leads/:id
DELETE /api/leads/:id
GET    /api/leads/:id/messages
POST   /api/leads/:id/messages
```

**Visitors (Sentinel):**
```
GET    /api/visitors
POST   /api/visitors          # Add new visitor
DELETE /api/visitors/:id      # Remove visitor
GET    /api/visitors/zones    # Zone analytics
POST   /api/alerts            # Trigger alert
```

**Inventory:**
```
GET    /api/units
GET    /api/units/:id
PATCH  /api/units/:id/status
GET    /api/units/availability
```

**Dashboard:**
```
GET /api/metrics              # Real-time metrics
GET /api/velocity             # Lead velocity data
GET /api/system-health        # System status
GET /api/activity             # Recent activity feed
```

### WebSocket Events

**Real-time Updates:**
```
ws://api.velocity.com/ws

Events:
- visitor:new
- visitor:update
- visitor:removed
- lead:new
- lead:updated
- metrics:update
- alert:triggered
```

---

## Performance Optimization

### Code Splitting

Vite automatically code-splits by route. Each module is lazy-loaded:

```typescript
const Dashboard = lazy(() => import('./components/modules/Dashboard'));
```

### Image Optimization

- Use WebP format
- Lazy load images with `loading="lazy"`
- Serve responsive images via `<picture>` tag

### Bundle Size

**Current Build:**
- JavaScript: ~300KB (gzipped)
- CSS: ~50KB (gzipped)

**Optimization Strategies:**
- Tree-shaking unused components
- Dynamic imports for heavy modules
- Remove unused Tailwind classes (purge)

---

## Security Considerations

### Authentication

- FaceID biometric authentication
- JWT token storage in LocalStorage (consider httpOnly cookies for production)
- Automatic logout on token expiration

### Data Privacy

- Visitor face data handled according to GDPR
- No PII stored in browser localStorage
- Encrypted WebSocket connections (WSS)

### Input Validation

- Zod schema validation on all forms
- Server-side validation required
- XSS protection via React's built-in escaping

---

## Testing Strategy

### Unit Tests (Recommended)

**Framework:** Vitest + React Testing Library

```bash
npm install -D vitest @testing-library/react @testing-library/jest-dom
```

**Test Coverage Targets:**
- Zustand store actions: 100%
- Component rendering: 80%
- User interactions: 70%

### E2E Tests (Recommended)

**Framework:** Playwright

```bash
npm install -D @playwright/test
```

**Critical Flows:**
- Login → Dashboard → Lead Interaction
- Visitor Alert Trigger → Response
- Unit Status Update

---

## Troubleshooting

### Common Issues

**Issue:** Build fails with TypeScript errors  
**Fix:** Run `npm run build` to see full errors, check `tsconfig.json`

**Issue:** Tailwind classes not applying  
**Fix:** Check `tailwind.config.js` content paths, restart dev server

**Issue:** Zustand state not persisting  
**Fix:** Clear localStorage `velocity-webos-storage`, check persistence config

**Issue:** Framer Motion animations janky  
**Fix:** Reduce `stiffness`, increase `damping`, check for layout shifts

---

## Roadmap

### Planned Features

- **Voice Commands:** Alexa/Google Assistant integration
- **AR Property Tours:** WebXR integration
- **Multi-language Support:** i18n with Arabic/English
- **Dark/Light Mode:** Theme switcher
- **Mobile App:** React Native version
- **Analytics Export:** PDF/Excel reports

---

## Contributors

**Development Team:** Desineuron - Project Velocity  
**Design System:** Custom Velocity UI  
**Built With:** ❤️ and ☕

---

**End of Technical Bible**