# Project Velocity — Component Reference

> **Stack:** React + TypeScript · Framer Motion · Tailwind CSS · Recharts · Three.js / React Three Fiber · Zustand (`useStore`)

---

## User Flow Overview

```
App Start
  └─ Not authenticated → LoginScreen
       ├─ FaceID tap → 2.5s scan animation → login()
       └─ "Use password instead" → password form → login()
            └─ Authenticated → MainLayout
                 ├─ Sidebar (always visible, collapsible)
                 └─ Active Module (one of 5 pages)
```

---

## 0 · Login Page
**File:** [src/components/layout/LoginScreen.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/layout/LoginScreen.tsx)

The entry gate to the OS. Simulates a biometric-first enterprise auth flow.

| Component / Element | Function | Reason |
|---|---|---|
| **Background ambient orbs** | Two animated `motion.div` blobs with `blur-3xl` | Creates depth and premium feel on an otherwise empty screen |
| **Login Card** | `motion.div` spring-animated card, `rounded-3xl`, glassmorphism surface | Focuses the user's eye; spring entry animation feels native/iOS-like |
| **Logo icon** (`Scan`) | Glowing blue square icon with `boxShadow` pulse | Brand mark; reinforces the "scanning / intelligence" theme |
| **FaceID Button** | Circular `motion.button`; on click triggers `isScanning` state → conic-gradient spinner + pulsing ring for 2.5s, then calls [login()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#247-248) | Primary auth path — simulates biometric scan UX |
| **"Use password instead"** | Text button that sets `showPassword = true` | Fallback for when FaceID isn't available |
| **Password Form** | `AnimatePresence` swap; `Lock` icon input + Submit button + "Back to FaceID" | Secondary auth path; accepts `"admin"` or empty string |
| **Error message** | `motion.p` slide-in red text | Inline validation feedback |
| **Footer** | `"Secured by On-Premise Python Backend"` | Communicates data sovereignty — important for enterprise real estate clients |

**State:** `isScanning`, `showPassword`, `password`, [error](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#535-536)

---

## 1 · Dashboard
**File:** [src/components/modules/Dashboard.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx)

The command center. Shows live KPIs, sentiment, system health, AI chat, and lead velocity at a glance.

### Layout
4-column CSS grid. Top row: 4 KPI cards. Middle row: Sentiment (2-col) + System Health (2-col). Bottom row: AI Chat (2-col, 2-row) + Lead Velocity (2-col, 2-row).

### Design Tokens
`GLASS` object — shared `background`, `border`, `backdropFilter`, `boxShadow` applied to every widget for visual consistency.

---

### Base Components

| Component | Function | Reason |
|---|---|---|
| **[Widget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Sentinel.tsx#42-74)** | Base `motion.div` wrapper: `rounded-2xl`, `overflow-hidden`, GLASS styles, entry animation (`opacity 0→1, y 18→0`), optional `glow` prop for stronger box-shadow | Single source of truth for all panel styling — change once, updates everywhere |
| **[LiveBadge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#143-156)** | Green pulsing dot + "Live" text | Communicates real-time data feed to the user |
| **[UpBadge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#157-166)** | Green `ArrowUpRight` + percentage text | Shows positive trend at a glance |

---

### KPI Cards (top row)

| Component | Metric | Glow Color | Function |
|---|---|---|---|
| **[ActiveVisitorsWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#167-182)** | `metrics.activeVisitors` | Blue `rgba(59,130,246,0.22)` | Shows how many people are physically in the showroom right now |
| **[TodayLeadsWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#183-198)** | `metrics.todayLeads` + converted count | Cyan `rgba(34,211,238,0.18)` | Tracks daily lead capture volume |
| **[ConversionRateWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#199-214)** | `metrics.conversionRate %` vs industry avg | Indigo `rgba(99,102,241,0.20)` | Key sales efficiency metric |
| **[TopPerformerWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#215-255)** | Hardcoded "Rania Al-Farsi" + deal stats | Amber `rgba(251,191,36,0.22)` | Gamification / motivation — highlights the top salesperson |

All four use **[StatWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#95-142)** internally:

| [StatWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#95-142) sub-element | Function |
|---|---|
| Large radial glow blob (bottom-right) | Ambient lighting effect matching reference image style |
| Secondary softer bloom (bottom-left) | Adds depth to the lighting |
| Icon (top-left) | Visual identifier for the metric type |
| Badge (top-right) | Live / trend indicator |
| Label (uppercase, muted) | Metric name |
| Value (large `text-4xl`) | The number — primary information |
| Sub-text | Context (e.g. "In Experience Center") |

---

### Middle Row

#### [SentimentGauge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/sentinel/JourneyRiver/InspectorPanel.tsx#5-53)
Shows the real-time emotional temperature of the showroom.

| Element | Function |
|---|---|
| Large blue glow bloom (bottom) | Lighting effect |
| Secondary indigo bloom (left) | Depth |
| Progress bar | Animated `motion.div` width from 0→value%; gradient blue fill with `boxShadow` glow |
| Label ("Showroom Vibe") | Context |
| Dynamic label ("Excellent" / "Good" / "Needs Attention") | Color-coded quick read |

#### [SystemHealth](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#312-402)
Shows CPU, GPU, Memory, Temperature of the on-premise backend server.

| Element | Function |
|---|---|
| Multi-color glow bloom (blue left, cyan right, purple center) | Lighting effect |
| 4× SVG circular arc gauges | Each animates `strokeDashoffset` from full→partial; `drop-shadow` filter for glow |
| "Optimal" badge | Quick system status |

---

### Bottom Row

#### [AIChatWidget](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#491-619) ("AI Onboard")
An embedded AI assistant for deal strategy.

| Element | Function |
|---|---|
| Avatar + "Online" badge | Humanizes the AI; shows it's active |
| Message list | Scrollable chat history; assistant messages left-aligned, user messages right-aligned with blue bubble |
| Auto-scroll (`useRef` + `scrollIntoView`) | Keeps latest message visible |
| Typing indicator (3 animated dots) | Simulates AI thinking |
| Input + Send button | User query entry |
| Sparkle icon button | Triggers AI response simulation |
| Mock response engine | Cycles through pre-written strategic responses |

**State:** `messages[]`, `input`, `isTyping`, `isFocused`

#### [LeadVelocityChart](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Dashboard.tsx#403-483)
Area chart showing generated vs. closed leads over time.

| Element | Function |
|---|---|
| Large blue + cyan glow blooms | Lighting effect |
| `AreaChart` (Recharts) | Visualizes lead pipeline velocity over the day |
| Two `Area` series (Generated / Closed) | Blue = generated leads, Cyan = closed deals |
| SVG gradient fills | Fade from color to transparent for depth |
| Custom `Tooltip` | Glassmorphism styled tooltip on hover |
| Legend dots | Color-coded series labels |

---

## 2 · The Oracle
**File:** [src/app/oracle/page.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx)

AI-powered CRM canvas. A natural language interface that renders different data views based on user prompts.

### Layout
Full-height split: **top AI insight banner** + **main canvas** (left: data view, right: AI chat bar).

### User Flow
```
User types prompt → queryOracle() → returns { view, data, insight }
  → Canvas switches to matching view (pipeline / team / timeline / map / calendar)
  → AI insight banner updates
  → Conversation history appended
```

---

| Component | Function | Reason |
|---|---|---|
| **AI Insight Banner** | Full-width blue-tinted bar showing the AI's top insight for the current view | Surfaces the most important takeaway without the user having to read the full data |
| **View Selector Pill** | Dropdown showing current view name (e.g. "Pipeline") | Lets user manually switch canvas views without typing |
| **[GlassFrame](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#65-72)** | Wrapper `div` with `GLASS_PANEL` styles | Consistent glassmorphism container for all canvas panels |

---

### Canvas Views

#### Kanban Pipeline (`pipeline`)
| Element | Function |
|---|---|
| 4 columns (New Leads / Qualified / Proposal Sent / Negotiation) | Represents deal stages |
| [PipelineCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#73-102) | Each deal: avatar, name, company, deal value badge; hover → blue glow border |
| Column count badge | Shows number of deals per stage |

#### Team Performance (`team_performance`)
| Element | Function |
|---|---|
| `LineChart` (Recharts) | Shows individual rep performance over time |
| Rep rows with avatar + stats | Name, deals closed, revenue, win rate |
| Rank badges | Visual hierarchy of performance |

#### Account Timeline (`account_timeline`)
| Element | Function |
|---|---|
| Timeline entries | Chronological activity log per account |
| Activity type icons | Call / Email / Meeting / Note |
| Contact cards | Avatar + name + company + last activity |

#### Geographic Lead Map (`lead_map`)
| Element | Function |
|---|---|
| Map placeholder with pin markers | Geographic distribution of leads |
| Lead count by region | Quantifies opportunity density |

#### Calendar & Tasks (`calendar_tasks`)
| Element | Function |
|---|---|
| Task list with due dates | Upcoming follow-ups and viewings |
| Priority badges | High / Medium / Low |
| Calendar grid | Visual scheduling view |

---

### AI Chat Bar (right panel)
| Element | Function |
|---|---|
| Conversation history | Shows user prompts + AI responses |
| Prompt mode selector | Dropdown to pick a pre-set view type |
| Text input | Free-form natural language query |
| Voice button ([Mic](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#525-543)) | Voice input trigger |
| Send button | Submits query |
| Sample prompt chips | One-click example queries to guide the user |

---

## 3 · The Sentinel
**File:** [src/components/modules/Sentinel.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Sentinel.tsx)

Real-time visitor intelligence. Tracks people physically in the showroom using AI facial analysis.

### Layout
Top row: 4 KPI stat cards. Middle: Zone Analytics (left) + AI Strategic Insights (right). Bottom: Sentiment Distribution (left) + Journey River (center) + Alert Panel (right).

---

### KPI Cards (top row)

| Component | Metric | Accent | Function |
|---|---|---|---|
| **Active Visitors** | Live count | Green | How many people are in the building right now |
| **Avg Sentiment** | % score | Blue | Overall emotional mood of all tracked visitors |
| **Detection Accuracy** | % confidence | Purple | AI model confidence — trust indicator |
| **Tracked Today** | Unique faces | Amber | Total unique individuals seen today |

All use a shared `StatCard` pattern with icon, label, large value, and sub-text.

---

### Zone Analytics
| Element | Function |
|---|---|
| Zone rows (A–D) | Main Showroom, Penthouse Gallery, Amenity Deck VR, Reception |
| Visitor count per zone | How many people are in each area |
| Sentiment % per zone | Color-coded: green (high) → amber (medium) → red (low) |
| Zone letter badge | Quick visual identifier |

**Reason:** Helps sales staff know where to focus attention — e.g. if Penthouse Gallery has 3 visitors at 85% sentiment, send a senior agent there.

---

### AI Strategic Insights
| Element | Function |
|---|---|
| 4 insight cards (2×2 grid) | One per tracked company/lead |
| Company name + deal stage badge | Context |
| AI-generated insight text | Behavioral analysis (e.g. "Key decision maker showed high engagement during VR tour") |
| Sentiment label (Positive / Neutral / Negative) | Color-coded quick read |
| "LIVE ANALYSIS" badge | Communicates real-time processing |

**Reason:** Converts raw behavioral data into actionable sales intelligence — the core value prop of the Sentinel.

---

### Sentiment Distribution
| Element | Function |
|---|---|
| 5 emotion rows (Excited / Interested / Neutral / Confused / Disinterested) | Breakdown of visitor emotional states |
| Emoji icons | Quick visual recognition |
| Animated progress bars | Width proportional to count |
| Count numbers | Exact figures |

---

### Journey River
**File:** `src/components/sentinel/JourneyRiver/`

The most complex visualization — an animated SVG path connecting tracked leads through their deal stages.

| Sub-component | Function |
|---|---|
| **[JourneyRiver](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/sentinel/JourneyRiver/index.tsx#162-284) (index)** | Container: lead list (left) + SVG canvas (center) + detail panel (right) |
| **Lead list** | Scrollable list of tracked companies with sentiment score badges; click to select |
| **[RiverPath](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/sentinel/JourneyRiver/RiverPath.tsx#25-240)** | Draws a smooth bezier curve from lead entry point to current deal stage; animated `pathLength` on mount; glow shadow duplicate path |
| **Sentiment Axis bar** | Horizontal gradient bar (red→amber→green) showing the sentiment spectrum |
| **Detail Panel** | Right-side panel showing selected lead's last interaction (call/meeting), sentiment score gauge, and summary text |

**Reason:** Makes the abstract concept of "deal pipeline" spatial and emotional — you can literally see the path a lead has taken.

---

### Alert Panel
| State | Elements | Function |
|---|---|---|
| **Active** (amber) | `AlertTriangle` icon + "Sentiment Alert" title + message + timestamp | Notifies staff of a visitor showing negative signals |
| **Clear** (green) | `ScanFace` icon + "All Clear" + "No alerts at this time" | Confirms no action needed |

`AnimatePresence` with `mode="wait"` handles the transition. Fixed `minHeight` prevents layout shift between states.

---

## 4 · Inventory
**File:** [src/components/modules/Inventory.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx)

Full property management system for the building's units. Browse, filter, view in 3D, and inspect floor plans.

### Layout
Top: 4 stat counters. Below: search + filter bar. Main: 2-column unit card grid (left) + Google Maps embed (right).

---

### Stat Counters (top row)

| Counter | Color | Function |
|---|---|---|
| **Total Units** | Blue | Total portfolio size |
| **Available** | Green | Units ready to sell |
| **Reserved** | Amber | Units with active interest |
| **Sold** | Purple | Completed transactions |

Each has an animated progress bar showing the percentage of total.

---

### Filter Bar
| Element | Function |
|---|---|
| Search input | Text filter on unit number, type, view |
| Filter pills (All Units / Available / Reserved / Sold / On Hold) | Status filter |
| Grid/List toggle buttons | Switch between card grid and compact list view |

---

### [UnitCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#431-560)
The primary browsing unit. Clicking opens [PropertyDetailModal](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#216-430).

| Element | Function |
|---|---|
| Status glow (top-right corner) | Ambient color: green=available, amber=reserved, purple=sold |
| "Unit Folder" label | Mimics a file system metaphor |
| Unit number + floor | Primary identifier |
| [StatusBadge](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#57-74) | Color-coded pill: Available / Reserved / Sold / On Hold |
| **Image → 3D preview on hover** | Static photo at rest; on `mouseEnter` swaps to a live Three.js [Canvas](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#505-513) with `autoRotate` | Wow factor — makes browsing feel like a product showcase |
| Type / Area / View tags | Key specs at a glance |
| Price | Primary decision metric |
| **3D Viewer button** | Opens [StudioWindow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#683-732) in `3d` mode |
| **Blueprint button** | Opens [StudioWindow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#683-732) in `blueprint` mode |

---

### [PropertyDetailModal](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#216-430)
Full-screen overlay with complete unit information.

| Section | Elements | Function |
|---|---|---|
| Header bar | Mac-style close buttons + unit number + status badge | Navigation + context |
| Hero image | Full-width photo with gradient overlay + price overlay | Visual impact |
| Description | Unit type + floor + prose description | Narrative sell |
| Key stats grid | Bedrooms / Bathrooms / Area / Floor | Quick spec comparison |
| Additional info | View / Parking / Type | Secondary specs |
| Features & Amenities | Cyan pill tags | Selling points |
| Quick-launch buttons | "3D Viewer" + "Blueprint Studio" | Direct access to visualization tools |
| Pricing card | Price + price/m² + area + floor + parking | Financial details |
| Payment Plan | Numbered steps (Booking / Construction / Handover %) | Financing structure |
| Availability card | Status + last updated date | Current state |

---

### [StudioWindow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#683-732)
Full-screen modal for immersive unit exploration.

| Mode | Component | Function |
|---|---|---|
| **3D Viewer** | [Viewer3D](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#111-154) → Three.js [Canvas](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/app/oracle/page.tsx#505-513) + [GlbModel](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#85-110) + `OrbitControls` | Interactive 3D walkthrough of the unit; mouse to rotate/pan/zoom |
| **Blueprint Studio** | [BlueprintViewer](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#561-682) | Zoomable/pannable floor plan image; scroll to zoom, drag to pan, +/−/⌂ controls |

[GlbModel](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#85-110) auto-normalizes the GLB scale to fit the viewport regardless of original model dimensions.

---

### [RightMapPane](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#733-751)
| Element | Function |
|---|---|
| Google Maps `iframe` | Shows the geographic location of the development (Dubai Marina) |
| Location label overlay | "Google Maps - Inventory Region" |
| Unit price grid (bottom) | Shows first 4 units with prices as a quick reference |

---

### [UnitRow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Inventory.tsx#753-824) (List View)
Compact table-style row for the list view toggle. Shows thumbnail + unit number + status badge + type/area tags + view + price in a single horizontal row.

---

## 5 · Settings
**File:** [src/components/modules/Settings.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx)

System configuration hub. 4 rows × 2 columns of glassmorphism cards.

### Shared Primitives

| Component | Function |
|---|---|
| **[GlassCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#36-57)** | `motion.div` with `GLASS` styles + staggered entry animation — base for all setting sections |
| **[SectionHeader](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#58-71)** | Icon badge + title with bottom border — consistent section labeling |
| **[SettingsRow](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#72-98)** | Label + optional description (left) + control (right) with bottom separator — standard settings list item |
| **[Toggle](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#99-116)** | Animated spring-based on/off switch; blue when on, grey when off |
| **[DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183)** | Custom dropdown with `AnimatePresence` animated menu; click-outside-to-close overlay |
| **[GhostButton](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#184-202)** | Subtle bordered button; `danger` prop for red variant |
| **[DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220)** | Text input with focus border highlight |

---

### Setting Sections

#### System Status ([SystemStatusCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#221-295))
| Element | Function |
|---|---|
| Backend connection pill | Green/red indicator + "Connected" / "Connection lost" |
| Version + Last Sync grid | Shows app version and last data sync time |
| **Sync Now** button | Triggers [updateStatus({ serverStatus: 'syncing' })](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#325-328) |
| **Restart** button | System restart action |

#### iOS App / Device ([IOSConnectionCard](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#296-401))
| Element | Function |
|---|---|
| Device status pill | Shows paired iPhone name or "No Device Paired" |
| Pairing Code display | `VLC-7F3A-9B2D` with copy button |
| Local IP display | `192.168.1.42:8765` with copy button |
| **Pair Device** button | 2s simulated pairing animation → "Paired" state |
| **Unpair** button (danger) | Appears after pairing |
| Push Notifications toggle | Enable/disable alerts to paired iPhone |

**State:** `paired`, `pairing`, `copied`

#### Profile ([ProfileSettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#402-440))
| Row | Control |
|---|---|
| Full Name | [DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220) |
| Email | [DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220) (type=email) |
| Phone | [DarkInput](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#203-220) (type=tel) |

Avatar shows user initials from `useStore().user.name`.

#### Notifications ([NotificationSettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#441-465))
5 toggle rows:
- New Lead Alerts
- Sentiment Alerts
- Viewing Reminders
- System Updates
- Daily Email Digest

#### Security ([SecuritySettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#466-504))
| Row | Control |
|---|---|
| Two-Factor Authentication | Toggle |
| Biometric Login (FaceID) | Toggle |
| Change Password | Ghost button |
| API Keys | Ghost button |
| Session Timeout | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (15min / 30min / 1hr / Never) |

#### Display ([DisplaySettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#505-547))
| Row | Control |
|---|---|
| Reduced Motion | Toggle |
| Compact Mode | Toggle |
| Language | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (English / العربية) |
| Timezone | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (Dubai / Riyadh / London) |

#### Data & Privacy ([DataSettings](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#548-581))
| Row | Control |
|---|---|
| Auto-Backup | Toggle (always on) |
| Data Retention | [DarkSelect](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#117-183) (30d / 90d / 6mo / 1yr) |
| Export Data | Ghost button |
| Clear Cache | Ghost button (danger/red) |

#### About ([AboutSection](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/modules/Settings.tsx#582-612))
- "V" logo mark with glow
- Version 2.1.0 · Build 2024.02.18
- Links: Terms of Service · Privacy Policy · Documentation

---

## Global Architecture

### [App.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/App.tsx) — Shell
| Element | Function |
|---|---|
| Auth gate | `isAuthenticated ? <MainLayout> : <LoginScreen>` |
| [MainLayout](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/App.tsx#40-141) | `min-h-screen flex` with pure black background; renders `<Sidebar>` + `<motion.main>` |
| Top Bar | Module title + "Project Velocity · v1.1" subtitle + user avatar dropdown |
| User dropdown | Avatar button → Settings navigation + Logout |
| `motion.main` | Animated width transition when sidebar expands/collapses |

### [Sidebar.tsx](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/components/layout/Sidebar.tsx) — Navigation
| Element | Function |
|---|---|
| Brand mark | "V" monogram when collapsed; "Velocity" + "v1.1" when expanded |
| Nav items | Dashboard / Oracle / Sentinel / Inventory / Settings with icons |
| Active indicator | Highlighted item for current module |
| Collapse toggle | Chevron button at bottom; animates width 64px ↔ 220px |
| Status dot | Green pulsing dot at bottom — system online indicator |

### [useStore.ts](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts) — Global State (Zustand)
| State slice | Contents |
|---|---|
| `user` | `{ id, name, role }` or `null` |
| `isAuthenticated` | Boolean |
| `activeModule` | `'dashboard' \| 'oracle' \| 'sentinel' \| 'inventory' \| 'settings'` |
| `sidebarExpanded` | Boolean |
| `metrics` | `{ activeVisitors, todayLeads, conversionRate, closedDeals, systemHealth, sentimentScore }` |
| `velocityData` | Time-series array for Lead Velocity chart |
| `status` | `{ isConnected, serverStatus, version, lastSync }` |
| `visitors` | Array of tracked [Visitor](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/types/index.ts#44-53) objects |
| Actions | [login()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#247-248), [logout()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#248-249), [setActiveModule()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#253-254), [toggleSidebar()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#254-255), [updateStatus()](file:///f:/Workin%20In%20Progress/DESINEURON/PROJECT%20VELOCITY/Software/app/src/store/useStore.ts#325-328) |