forked from sagnik/Project_Velocity
863 lines
23 KiB
Markdown
863 lines
23 KiB
Markdown
# 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**
|