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: sagnik/Project_Velocity#5
2026-03-10 01:36:27 +05:30
parent cb6c752c8e
commit 55bb5e5a90
53 changed files with 11956 additions and 2222 deletions
--- a/Context/Bibels/velocity_component_reference.md
+++ b/Context/Bibels/velocity_component_reference.md
@@ -0,0 +1,517 @@
+# 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) |