Project_Velocity/.Agent Context/velocity_technical_bible.md

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

'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

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

NavigationState

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

OracleState

{
  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

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

DashboardState

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

InventoryState

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

SystemState

{
  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

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:

-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

.glass                /* Subtle glass effect */
.glass-strong         /* Bold glass effect */
.glass-panel          /* Panel with blur */
.glass-card           /* Card with gradient + blur */

Implementation

.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:

.sentiment-excited    /* Green */
.sentiment-confused   /* Amber */
.sentiment-neutral    /* Gray */

Status Pulse:

.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:

// 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:

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:

transition={{ 
  type: 'spring', 
  stiffness: 300, 
  damping: 30,
  mass: 0.8 
}}

State Management Patterns

Selective Subscriptions:

const activeModule = useStore((state) => state.activeModule);

Batch Updates:

set((state) => ({
  ...state,
  multiple: updates,
}));

---

Build & Deployment

Scripts

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:

VITE_API_URL=https://api.velocity.com
VITE_FACEID_KEY=your_key_here
VITE_ORACLE_AI_KEY=your_key_here

Access in code:

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:

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

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

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