Project_Velocity/.Agent Context/Bibels/velocity_component_reference.md

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

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()	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

---

1 · Dashboard

File: 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	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	Green pulsing dot + "Live" text	Communicates real-time data feed to the user
UpBadge	Green ArrowUpRight + percentage text	Shows positive trend at a glance

---

KPI Cards (top row)

Component	Metric	Glow Color	Function
ActiveVisitorsWidget	metrics.activeVisitors	Blue rgba(59,130,246,0.22)	Shows how many people are physically in the showroom right now
TodayLeadsWidget	metrics.todayLeads + converted count	Cyan rgba(34,211,238,0.18)	Tracks daily lead capture volume
ConversionRateWidget	metrics.conversionRate % vs industry avg	Indigo rgba(99,102,241,0.20)	Key sales efficiency metric
TopPerformerWidget	Hardcoded "Rania Al-Farsi" + deal stats	Amber rgba(251,191,36,0.22)	Gamification / motivation — highlights the top salesperson

All four use StatWidget internally:

StatWidget 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

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

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 ("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

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

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	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	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)	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

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 (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	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

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

The primary browsing unit. Clicking opens PropertyDetailModal.

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	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 with autoRotate
Type / Area / View tags	Key specs at a glance
Price	Primary decision metric
3D Viewer button	Opens StudioWindow in 3d mode
Blueprint button	Opens StudioWindow in blueprint mode

---

PropertyDetailModal

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

Full-screen modal for immersive unit exploration.

Mode	Component	Function
3D Viewer	Viewer3D → Three.js Canvas + GlbModel + OrbitControls	Interactive 3D walkthrough of the unit; mouse to rotate/pan/zoom
Blueprint Studio	BlueprintViewer	Zoomable/pannable floor plan image; scroll to zoom, drag to pan, +/−/⌂ controls

GlbModel auto-normalizes the GLB scale to fit the viewport regardless of original model dimensions.

---

RightMapPane

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 (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

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

Shared Primitives

Component	Function
GlassCard	motion.div with GLASS styles + staggered entry animation — base for all setting sections
SectionHeader	Icon badge + title with bottom border — consistent section labeling
SettingsRow	Label + optional description (left) + control (right) with bottom separator — standard settings list item
Toggle	Animated spring-based on/off switch; blue when on, grey when off
DarkSelect	Custom dropdown with AnimatePresence animated menu; click-outside-to-close overlay
GhostButton	Subtle bordered button; danger prop for red variant
DarkInput	Text input with focus border highlight

---

Setting Sections

System Status (SystemStatusCard)

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' })
Restart button	System restart action

iOS App / Device (IOSConnectionCard)

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)

Row	Control
Full Name	DarkInput
Email	DarkInput (type=email)
Phone	DarkInput (type=tel)

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

Notifications (NotificationSettings)

5 toggle rows:

• New Lead Alerts
• Sentiment Alerts
• Viewing Reminders
• System Updates
• Daily Email Digest

Security (SecuritySettings)

Row	Control
Two-Factor Authentication	Toggle
Biometric Login (FaceID)	Toggle
Change Password	Ghost button
API Keys	Ghost button
Session Timeout	DarkSelect (15min / 30min / 1hr / Never)

Display (DisplaySettings)

Row	Control
Reduced Motion	Toggle
Compact Mode	Toggle
Language	DarkSelect (English / العربية)
Timezone	DarkSelect (Dubai / Riyadh / London)

Data & Privacy (DataSettings)

Row	Control
Auto-Backup	Toggle (always on)
Data Retention	DarkSelect (30d / 90d / 6mo / 1yr)
Export Data	Ghost button
Clear Cache	Ghost button (danger/red)

About (AboutSection)

• "V" logo mark with glow
• Version 2.1.0 · Build 2024.02.18
• Links: Terms of Service · Privacy Policy · Documentation

---

Global Architecture

App.tsx — Shell

Element	Function
Auth gate	isAuthenticated ? <MainLayout> : <LoginScreen>
MainLayout	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 — 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 — 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 objects
Actions	login(), logout(), setActiveModule(), toggleSidebar(), updateStatus()