feat: Build the Dream Weaver interior restyling workflow to preserve room geometry while changing aesthetics (#5)
#3 Self-approved and unit tests passed with flying colors. Co-authored-by: Sagnik <sagnik7896@gmail.com> Reviewed-on: #5
This commit was merged in pull request #5.
This commit is contained in:
862
.Agent Context/Bibels/velocity_technical_bible.md
Normal file
862
.Agent Context/Bibels/velocity_technical_bible.md
Normal file
@@ -0,0 +1,862 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user