mula

Text Generation

Transformers

Eval Results (legacy)

text-generation-inference

Model card Files Files and versions

xet

Community

Hermit11 commited on 24 days ago

Commit

85a930a

verified ·

1 Parent(s): 2f7db6d

Upload DriveSmart_Dashboard_PRD.md

Browse files

Files changed (1) hide show

DriveSmart_Dashboard_PRD.md +882 -0

DriveSmart_Dashboard_PRD.md ADDED Viewed

	@@ -0,0 +1,882 @@

+# DriveSmart AI — Instructor Dashboard
+## Product Requirements Document (PRD)
+### For: lovable.dev / v0.dev Frontend Generation
+### Version: 1.0 | Status: Ready for Development
+---
+## 1. Project Overview
+**Product Name:** DriveSmart AI Instructor Dashboard
+**Purpose:** A web-based dashboard for driving school instructors to upload and manage training materials, monitor learner engagement, and configure their AI assistant — which serves learners 24/7 via WhatsApp.
+**Primary User:** Driving school instructors and administrators
+**Secondary Users:** Driving school managers / executives (read-only analytics view)
+---
+## 2. Brand Identity & Design System
+### 2.1 Brand Colours (AA Kenya — strictly follow these)
+```css
+:root {
+  /* Primary Palette */
+  --green-900:  #0F3D1A;   /* deepest green — hero backgrounds */
+  --green-700:  #1A5C2A;   /* primary brand green — nav, buttons, headers */
+  --green-500:  #2E8B46;   /* hover states, active indicators */
+  --green-100:  #E8F5EC;   /* light tinted backgrounds, cards */
+  /* Accent Palette */
+  --yellow-500: #F5C200;   /* primary yellow — CTAs, highlights, badges */
+  --yellow-300: #FFD84D;   /* hover state for yellow elements */
+  --yellow-100: #FFF8D6;   /* light yellow tint for alerts, info banners */
+  /* Neutral Palette */
+  --white:      #FFFFFF;
+  --gray-50:    #F8F9FA;
+  --gray-100:   #F1F3F5;
+  --gray-200:   #E9ECEF;
+  --gray-400:   #ADB5BD;
+  --gray-600:   #6C757D;
+  --gray-800:   #343A40;
+  --black:      #0A0A0A;
+  /* Semantic */
+  --success:    #2E8B46;
+  --warning:    #F5C200;
+  --error:      #D63031;
+  --info:       #0984E3;
+}
+```
+### 2.2 Typography
+```css
+/* Import in <head> */
+@import url('https://fonts.googleapis.com/css2?family=Barlow+Condensed:wght@600;700;800&family=DM+Sans:wght@400;500;600&family=DM+Mono:wght@400;500&display=swap');
+:root {
+  --font-display:  'Barlow Condensed', sans-serif;  /* headings, hero text, nav */
+  --font-body:     'DM Sans', sans-serif;            /* body, labels, UI text */
+  --font-mono:     'DM Mono', monospace;             /* code blocks, IDs, stats */
+}
+```
+**Type Scale:**
+| Token | Size | Weight | Font | Usage |
+|---|---|---|---|---|
+| `--text-hero` | 3.5rem / 56px | 800 | Barlow Condensed | Page hero titles |
+| `--text-h1` | 2.25rem / 36px | 700 | Barlow Condensed | Section headings |
+| `--text-h2` | 1.5rem / 24px | 600 | Barlow Condensed | Card headings |
+| `--text-h3` | 1.125rem / 18px | 600 | DM Sans | Subsection labels |
+| `--text-body` | 0.9375rem / 15px | 400 | DM Sans | Body copy |
+| `--text-small` | 0.8125rem / 13px | 400 | DM Sans | Captions, metadata |
+| `--text-mono` | 0.875rem / 14px | 500 | DM Mono | Stats, codes, counts |
+### 2.3 Checkered Brand Pattern
+The AA Kenya diagonal checkered pattern (green + yellow squares) is a signature brand element. Implement it as a CSS background pattern used as decorative accents — NOT as full-page backgrounds.
+```css
+/* Checkered accent strip — used as section dividers, card top-borders */
+.checkered-strip {
+  background-image:
+    repeating-conic-gradient(
+      var(--green-700) 0% 25%,
+      var(--yellow-500) 0% 50%
+    );
+  background-size: 16px 16px;
+  height: 8px;
+  width: 100%;
+}
+/* Thin checkered border top on highlighted cards */
+.card--featured::before {
+  content: '';
+  display: block;
+  height: 5px;
+  background-image: repeating-conic-gradient(
+    var(--green-700) 0% 25%, var(--yellow-500) 0% 50%
+  );
+  background-size: 10px 10px;
+}
+```
+### 2.4 Spacing & Radius
+```css
+:root {
+  --radius-sm:  4px;
+  --radius-md:  8px;
+  --radius-lg:  12px;
+  --radius-xl:  20px;
+  --space-1: 4px;   --space-2: 8px;   --space-3: 12px;
+  --space-4: 16px;  --space-6: 24px;  --space-8: 32px;
+  --space-10: 40px; --space-12: 48px; --space-16: 64px;
+}
+```
+### 2.5 Shadows
+```css
+:root {
+  --shadow-sm:  0 1px 3px rgba(0,0,0,0.08), 0 1px 2px rgba(0,0,0,0.06);
+  --shadow-md:  0 4px 12px rgba(0,0,0,0.10), 0 2px 4px rgba(0,0,0,0.06);
+  --shadow-lg:  0 10px 30px rgba(0,0,0,0.12), 0 4px 8px rgba(0,0,0,0.08);
+  --shadow-green: 0 4px 20px rgba(26, 92, 42, 0.25);
+  --shadow-yellow: 0 4px 20px rgba(245, 194, 0, 0.30);
+}
+```
+---
+## 3. Animation & Motion System
+### 3.1 Motion Philosophy
+**"Purposeful momentum"** — Every animation communicates state, not just decoration. Fast in, slower out. Elements that enter from a direction leave in the same direction. No bouncing, no elastic — the design is authoritative and professional.
+### 3.2 Core Transitions
+```css
+:root {
+  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);   /* general transitions */
+  --ease-enter:    cubic-bezier(0.0, 0, 0.2, 1);    /* elements entering */
+  --ease-exit:     cubic-bezier(0.4, 0, 1, 1);      /* elements leaving */
+  --ease-sharp:    cubic-bezier(0.4, 0, 0.6, 1);    /* quick snappy moves */
+  --duration-fast:   120ms;
+  --duration-base:   220ms;
+  --duration-slow:   380ms;
+  --duration-reveal: 500ms;
+}
+```
+### 3.3 Animation Catalogue
+**Page Entry (staggered reveal):**
+```css
+/* Apply to dashboard cards, table rows on page load */
+@keyframes fadeSlideUp {
+  from { opacity: 0; transform: translateY(18px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.card { animation: fadeSlideUp var(--duration-reveal) var(--ease-enter) both; }
+.card:nth-child(1) { animation-delay: 0ms; }
+.card:nth-child(2) { animation-delay: 60ms; }
+.card:nth-child(3) { animation-delay: 120ms; }
+.card:nth-child(4) { animation-delay: 180ms; }
+```
+**Stat Counter Animation:**
+```javascript
+// Animate numbers counting up on dashboard load
+// e.g. 0 → 1,247 over 1000ms using requestAnimationFrame
+// Use easeOutExpo easing for satisfying deceleration
+function animateCount(el, from, to, duration) { ... }
+```
+**Sidebar Navigation Active Indicator:**
+```css
+/* Sliding green pill indicator for active nav item */
+.nav-indicator {
+  position: absolute;
+  left: 0; top: 0;
+  width: 3px; height: 100%;
+  background: var(--yellow-500);
+  transition: transform var(--duration-base) var(--ease-standard);
+}
+```
+**Upload Drop Zone:**
+```css
+@keyframes dashedBorderPulse {
+  0%, 100% { border-color: var(--gray-400); }
+  50% { border-color: var(--green-500); }
+}
+/* On drag-over: smooth scale up + green glow */
+.dropzone--active {
+  transform: scale(1.02);
+  box-shadow: var(--shadow-green);
+  transition: all var(--duration-base) var(--ease-enter);
+}
+```
+**Document Processing Progress Bar:**
+```css
+@keyframes progressShimmer {
+  from { background-position: -200% center; }
+  to   { background-position: 200% center; }
+}
+.progress-bar--processing {
+  background: linear-gradient(
+    90deg,
+    var(--green-500) 0%,
+    var(--yellow-500) 50%,
+    var(--green-500) 100%
+  );
+  background-size: 200% auto;
+  animation: progressShimmer 1.8s linear infinite;
+}
+```
+**Toast Notifications:**
+- Enter: slide in from top-right, fade in — 220ms
+- Exit: slide out to right, fade out — 180ms
+- Auto-dismiss after 4s with shrinking progress bar at bottom
+**Modal:**
+- Backdrop: fade in 200ms
+- Panel: scale from 0.95 → 1.0 + fade in, 250ms ease-enter
+- Exit: reverse at 180ms
+**Button States:**
+```css
+.btn-primary {
+  transition: transform var(--duration-fast), box-shadow var(--duration-fast);
+}
+.btn-primary:hover  { transform: translateY(-1px); box-shadow: var(--shadow-green); }
+.btn-primary:active { transform: translateY(0px);  box-shadow: none; }
+```
+---
+## 4. Application Architecture
+### 4.1 Tech Stack (for lovable.dev / v0.dev)
+- **Framework:** Next.js 14 (App Router)
+- **Styling:** Tailwind CSS with custom config extending AA Kenya tokens
+- **Auth:** `@supabase/ssr` + `@supabase/supabase-js`
+- **File Upload:** `@supabase/storage-js` (direct-to-bucket)
+- **State:** React Context + `useState`/`useReducer` (no Redux)
+- **Icons:** `lucide-react`
+- **Charts:** `recharts`
+- **Notifications:** Custom toast system (no library)
+- **Drag & Drop:** `react-dropzone`
+### 4.2 Route Structure
+```
+/                        → redirect to /auth/login
+/auth/login              → Login page (public)
+/auth/forgot-password    → Password reset (public)
+/dashboard               → Overview / home (protected)
+/dashboard/documents     → Document library (protected)
+/dashboard/upload        → Upload new document (protected)
+/dashboard/analytics     → Usage analytics (protected)
+/dashboard/settings      → Account & system settings (protected)
+```
+### 4.3 Environment Variables (Supabase + n8n)
+```env
+# .env.local — provide these to the generated frontend
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+NEXT_PUBLIC_N8N_WEBHOOK_BASE=https://your-n8n-domain.com/webhook
+NEXT_PUBLIC_N8N_API_SECRET=your-shared-secret
+```
+---
+## 5. Pages — Detailed Specifications
+---
+### 5.1 Authentication — Login Page (`/auth/login`)
+**Layout:** Full-screen split. Left panel: brand/visual. Right panel: form.
+**Left Panel (40% width on desktop, hidden on mobile):**
+- Background: `var(--green-900)` — deep forest green
+- AA Kenya logo centered (white version)
+- Tagline: "Inspiring Mobility" in `--font-display`, `--yellow-500`
+- Below tagline: checkered strip (horizontal, full width of panel)
+- Subtle road texture overlay — dark semi-transparent diagonal lines at 15deg suggesting tarmac grain (`opacity: 0.07`)
+- Quote at bottom: *"Equipping drivers with knowledge for safer roads"* — white, italic, small
+**Right Panel (60% width on desktop, 100% on mobile):**
+- Background: `--white`
+- Top-right corner: small checkered square motif (decorative, 40×40px)
+- Vertical center-aligned form
+**Form Elements:**
+```
+[AA Logo — small, green version]           ← shown only on mobile
+[H1: "Welcome back"]                       ← Barlow Condensed 700, green-700
+[Subtext: "Sign in to your instructor dashboard"]
+[Label: "Email address"]
+[Input: email — full width]
+[Label: "Password"]
+[Input: password �� with show/hide toggle]
+[Row: spacer | "Forgot password?" link]    ← right-aligned, yellow-500
+[Button: "Sign In"]                        ← full width, green-700 bg, white text
+[Divider line]
+[Small text: "Need access? Contact your administrator."]
+```
+**Behaviour:**
+- On submit: button shows loading spinner (replacing text), disabled
+- On error: input borders turn `--error`, error message slides down below input (18px DM Sans, error red)
+- On success: brief green checkmark flash, then router.push('/dashboard') with page transition
+- Form validation: inline, on blur
+**Animations:**
+- Right panel form elements: staggered fadeSlideUp on mount (logo → title → inputs → button), 60ms delay each
+- Left panel: subtle parallax on mouse move — logo shifts ±8px, tagline shifts ±4px
+- Logo: on hover, slow rotation of the AA badge inner ring (360deg, 3s, infinite, ease-in-out)
+---
+### 5.2 Forgot Password (`/auth/forgot-password`)
+Simple centered card, white background with green-900 header strip.
+- Email input + "Send Reset Link" button
+- Success state: green checkmark + "Check your email" message
+- Back to login link
+---
+### 5.3 App Shell — Persistent Layout (all `/dashboard/*` routes)
+**Structure:**
+```
+┌─────────────────────────────────────────────────────┐
+│  TOPBAR (full width, 64px height)                   │
+├──────────┬──────────────────────────────────────────┤
+│          │                                          │
+│ SIDEBAR  │         MAIN CONTENT AREA                │
+│ (240px)  │         (fluid, scrollable)              │
+│          │                                          │
+└──────────┴──────────────────────────────────────────┘
+```
+**Topbar:**
+- Background: `var(--green-700)`
+- Left: hamburger menu icon (mobile) | "DriveSmart AI" wordmark in Barlow Condensed, white
+- Right: notification bell (with badge count) | Avatar circle with initials | Dropdown (Profile, Settings, Sign Out)
+- Bottom border: 4px checkered strip (green-700/yellow-500)
+- On scroll: add `box-shadow: var(--shadow-md)` transition
+**Sidebar:**
+- Background: `var(--green-900)`
+- Top: AA Kenya logo (small, white) with "Instructor Portal" label below in gray-400
+- Navigation items:
+  ```
+  [icon] Overview         /dashboard
+  [icon] Documents        /dashboard/documents
+  [icon] Upload           /dashboard/upload
+  [icon] Analytics        /dashboard/analytics
+  ─────────────────
+  [icon] Settings         /dashboard/settings
+  [icon] Sign Out
+  ```
+- Active item: white text + yellow-500 left border (3px) + green-500 background
+- Hover item: green-700 background, 200ms transition
+- Collapse button at bottom (mobile: slides out as drawer)
+- Bottom of sidebar: version number + "Powered by Gemini AI" in small gray text
+**Mobile:** Sidebar is a slide-in drawer from left, triggered by hamburger. Backdrop overlay fades in.
+---
+### 5.4 Dashboard Overview (`/dashboard`)
+**Hero Stats Row — 4 cards:**
+```
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│ 📄 Documents │ │ ❓ Queries   │ │ 👥 Learners  │ │ ✅ Resolved  │
+│     12       │ │    1,247     │ │     89       │ │    94.2%     │
+│  +2 this week│ │ +18 today    │ │  this month  │ │  resolution  │
+└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
+```
+- Card style: white bg, `--shadow-sm`, `--radius-lg`
+- Featured card (Queries): `card--featured` with checkered top border
+- Stats animate up from 0 on page load (easeOutExpo, 1000ms)
+- Subtle hover: translateY(-2px) + shadow-md
+**Quick Actions Row:**
+```
+[+ Upload Document]  [View Analytics]  [Open WhatsApp Preview]
+```
+- Primary: green-700 bg
+- Secondary: outlined green-700 border
+- Tertiary: yellow-500 bg, green-900 text
+**Recent Documents Table:**
+- Last 5 uploaded documents
+- Columns: Name | Type | Status | Chunks | Uploaded | Actions
+- Status badges: `pending` (gray), `processing` (yellow, animated shimmer), `ready` (green), `failed` (red)
+- Actions: View, Delete
+- "View all" link to `/dashboard/documents`
+**Activity Feed (right column, 30% width):**
+- Recent WhatsApp queries (last 10)
+- Each entry: phone number (masked: +254 7XX XXX X89) | input type icon | query preview (truncated 50 chars) | time ago
+- Input type icons: 💬 text | 🎙️ voice | 📷 image
+- Scrollable with custom scrollbar styled in green
+**Animations:**
+- Stats cards: staggered entry (0ms, 80ms, 160ms, 240ms)
+- Activity feed: items slide in from right, staggered 30ms each
+- Processing status cards pulse with green glow
+---
+### 5.5 Document Library (`/dashboard/documents`)
+**Header:**
+```
+[H1: "Document Library"]
+[Subtext: "X documents · Y total chunks indexed"]
+[Right: "+ Upload New" button]
+```
+**Filters & Search Bar:**
+```
+[🔍 Search documents...] [Type ▾] [Status ▾] [Date ▾] [Sort ▾]
+```
+**Document Grid (default view) | List toggle:**
+**Card Mode (2–3 columns responsive grid):**
+```
+┌─────────────────────────────┐
+│ [Checkered top border 5px]  │
+│ [🗎 icon — large, green]    │
+│                             │
+│ [Document name — truncated] │
+│ [File type badge]           │
+│                             │
+│ [Chunks: 47] [Size: 2.3MB]  │
+│ [Uploaded: 2 days ago]      │
+│ [Status badge]              │
+│                             │
+│ [──────────────────────────] │
+│ [Delete]         [View →]   │
+└─────────────────────────────┘
+```
+**List Mode:**
+- Full-width table rows with hover highlight (green-100)
+- Sortable column headers with sort direction arrows
+**Empty State:**
+```
+[Large dashed border box — center of page]
+[Document illustration or road-sign icon in green-200]
+[H2: "No documents yet"]
+[Body: "Upload your first training material to get started."]
+[Button: "+ Upload Document"]
+```
+**Delete Confirmation:**
+- Modal with warning icon
+- "This will remove [filename] and all [N] indexed chunks. Learners will no longer have access to this content."
+- [Cancel] [Delete Document] — red destroy button
+---
+### 5.6 Document Upload (`/dashboard/upload`)
+**Layout:** Centered, max-width 720px
+**Step Indicator:**
+```
+[1 Select File] ──── [2 Processing] ──── [3 Complete]
+```
+Yellow active step, green completed steps, gray-400 upcoming.
+**Step 1 — File Selection:**
+Drop Zone:
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│   [Cloud upload icon — 48px, green-700]         │
+│                                                 │
+│   Drop your file here, or click to browse       │
+│   Supports: PDF, DOCX, TXT · Max 50MB           │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+- Border: 2px dashed gray-300, radius-xl
+- Drag-over: scale(1.02), green border, green-100 bg, shadow-green
+- File preview after selection: filename, size, type icon, remove button
+Document Name Field:
+- Auto-populated from filename (editable)
+- Character count: 0/100
+[Upload & Process] button — disabled until file selected, green-700
+**Step 2 — Processing (auto-navigated after upload):**
+```
+[Animated document icon with pages flipping — CSS animation]
+Processing "Traffic Rules Kenya 2024.pdf"
+[Progress bar — green-500 shimmer animation]
+Step 1 of 3: Uploading to storage...     ✅
+Step 2 of 3: Extracting text...          ⏳ (spinning indicator)
+Step 3 of 3: Generating embeddings...    ○ (pending)
+This may take 30–90 seconds depending on document size.
+```
+- Poll n8n webhook every 3 seconds for status update
+- Polled via: `GET /webhook/document-status?id={id}` with JWT
+**Step 3 — Complete:**
+```
+[Large green checkmark — animated draw-on SVG stroke]
+"Training material ready!"
+"Traffic Rules Kenya 2024.pdf"
+47 knowledge chunks indexed and ready for learner queries.
+[View in Library] [Upload Another]
+```
+---
+### 5.7 Analytics (`/dashboard/analytics`)
+**Date Range Selector:** Today | Last 7d | Last 30d | Custom
+Sticky below topbar on scroll.
+**Top Row — KPI Cards:**
+```
+Total Queries | Voice Queries | Image Queries | Avg Response Time
+```
+**Input Type Distribution — Donut Chart:**
+- Colors: Text=green-700, Voice=yellow-500, Image=green-500
+- Recharts `PieChart` + custom tooltip
+**Queries Over Time — Line Chart:**
+- X-axis: dates | Y-axis: query count
+- Green line, yellow fill below line at 15% opacity
+- Smooth curve (`type="monotone"`)
+- Custom dot on hover: green circle + tooltip card
+**Top Questions Table:**
+```
+# | Question (truncated) | Count | Input Type | Last Asked
+─────────────────────────────────────────────────────────
+1 | What does a yield sign mean?  | 34 | 💬 | 2h ago
+2 | Speed limit in school zones   | 28 | 🎙️ | 5h ago
+...
+```
+- Hover row: green-100 bg
+**Document Usage Breakdown:**
+- Horizontal bar chart showing which documents are cited most in responses
+- Bars: green-700 fill, yellow-500 for top document
+---
+### 5.8 Settings (`/dashboard/settings`)
+**Sections (tabbed or accordion):**
+**Profile:**
+- Name, Email (read-only — managed by Supabase)
+- Change Password form
+- Avatar upload (stored in Supabase Storage)
+**WhatsApp Configuration:**
+```
+WhatsApp Phone Number ID:   [__________________]
+Meta Access Token:          [__________________] [Show/Hide]
+Webhook Verify Token:       [__________________] [Copy]
+n8n Webhook URL:            [read-only display]  [Copy]
+```
+Each field: save inline with green checkmark on success.
+**AI Configuration:**
+```
+Response Language:          [English ▾] [Swahili ▾] [Both]
+Max Response Length:        [Concise] [Standard ●] [Detailed]
+Web Search:                 [Toggle — ON/OFF]
+Voice Reply Language:       [English ▾]
+```
+**Danger Zone:**
+- "Delete all documents and embeddings" — outlined red button → confirmation modal
+---
+## 6. Component Library
+### 6.1 Button Variants
+```
+[Primary]    → bg: green-700 | text: white | hover: green-500
+[Secondary]  → bg: white | border: green-700 | text: green-700 | hover: green-100
+[Accent]     → bg: yellow-500 | text: green-900 | hover: yellow-300
+[Danger]     → bg: white | border: error | text: error | hover: error bg
+[Ghost]      → no bg/border | text: green-700 | hover: green-100 bg
+[Loading]    → spinner replaces text, disabled, reduced opacity
+```
+All buttons: `--radius-md`, `--duration-fast` transition, `translateY(-1px)` on hover.
+### 6.2 Status Badges
+```css
+.badge--pending    { bg: gray-200;    color: gray-600;  }
+.badge--processing { bg: yellow-100;  color: yellow-700; /* + shimmer */ }
+.badge--ready      { bg: green-100;   color: green-700; }
+.badge--failed     { bg: error-light; color: error;     }
+```
+### 6.3 Input Fields
+```css
+.input {
+  border: 1.5px solid var(--gray-200);
+  border-radius: var(--radius-md);
+  padding: 10px 14px;
+  font: var(--font-body);
+  transition: border-color var(--duration-fast), box-shadow var(--duration-fast);
+}
+.input:focus {
+  border-color: var(--green-700);
+  box-shadow: 0 0 0 3px rgba(26, 92, 42, 0.12);
+  outline: none;
+}
+.input--error {
+  border-color: var(--error);
+  box-shadow: 0 0 0 3px rgba(214, 48, 49, 0.10);
+}
+```
+### 6.4 Toast Notification
+Position: top-right, 16px from edges, z-index: 9999
+```
+┌──────────────────────────────┐
+│ ✅  Document uploaded        │
+│     Processing has started   │
+│ ████████████░░░░░░░░░░░░░░   │ ← auto-dismiss progress bar
+└──────────────────────────────┘
+```
+Types: success (green), warning (yellow), error (red), info (blue)
+Animation: slide in from right + fade, auto-dismiss 4s
+---
+## 7. Supabase Integration
+### 7.1 Auth Setup
+```javascript
+// lib/supabase.js
+import { createClient } from '@supabase/supabase-js'
+export const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
+)
+```
+```javascript
+// middleware.js — protect /dashboard/* routes
+import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs'
+export async function middleware(req) {
+  const res = NextResponse.next()
+  const supabase = createMiddlewareClient({ req, res })
+  const { data: { session } } = await supabase.auth.getSession()
+  if (!session && req.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/auth/login', req.url))
+  }
+  return res
+}
+export const config = { matcher: ['/dashboard/:path*'] }
+```
+### 7.2 File Upload to Supabase Storage
+```javascript
+async function uploadDocument(file, documentName) {
+  // 1. Insert metadata record first
+  const { data: doc, error: dbError } = await supabase
+    .from('documents')
+    .insert({ name: documentName, file_type: file.type, status: 'pending' })
+    .select()
+    .single()
+  if (dbError) throw dbError
+  // 2. Upload file to storage
+  const filePath = `${doc.id}/${file.name}`
+  const { error: storageError } = await supabase.storage
+    .from('training-documents')
+    .upload(filePath, file)
+  if (storageError) throw storageError
+  // 3. Get signed URL (1 hour expiry)
+  const { data: urlData } = await supabase.storage
+    .from('training-documents')
+    .createSignedUrl(filePath, 3600)
+  // 4. Trigger n8n ingestion workflow
+  const session = await supabase.auth.getSession()
+  await fetch(`${process.env.NEXT_PUBLIC_N8N_WEBHOOK_BASE}/ingest`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.data.session.access_token}`,
+      'x-api-secret': process.env.NEXT_PUBLIC_N8N_API_SECRET
+    },
+    body: JSON.stringify({
+      document_id: doc.id,
+      signed_url: urlData.signedUrl,
+      file_name: file.name,
+      file_type: file.type
+    })
+  })
+  return doc.id
+}
+```
+### 7.3 Polling Document Status
+```javascript
+// Poll every 3 seconds until status is 'ready' or 'failed'
+async function pollDocumentStatus(documentId, onUpdate) {
+  const interval = setInterval(async () => {
+    const { data } = await supabase
+      .from('documents')
+      .select('status, chunk_count')
+      .eq('id', documentId)
+      .single()
+    onUpdate(data)
+    if (data.status === 'ready' || data.status === 'failed') {
+      clearInterval(interval)
+    }
+  }, 3000)
+  return () => clearInterval(interval) // cleanup
+}
+```
+### 7.4 Fetching Analytics from n8n
+```javascript
+async function fetchAnalytics(range = '7d') {
+  const session = await supabase.auth.getSession()
+  const res = await fetch(
+    `${process.env.NEXT_PUBLIC_N8N_WEBHOOK_BASE}/stats?range=${range}`,
+    {
+      headers: {
+        'Authorization': `Bearer ${session.data.session.access_token}`,
+        'x-api-secret': process.env.NEXT_PUBLIC_N8N_API_SECRET
+      }
+    }
+  )
+  return res.json()
+}
+```
+---
+## 8. Responsive Breakpoints
+```css
+/* Mobile-first */
+--bp-sm:  640px;   /* large phone landscape */
+--bp-md:  768px;   /* tablet portrait */
+--bp-lg:  1024px;  /* tablet landscape / small laptop */
+--bp-xl:  1280px;  /* desktop */
+--bp-2xl: 1536px;  /* wide desktop */
+```
+| Element | Mobile (<768px) | Tablet (768–1024px) | Desktop (>1024px) |
+|---|---|---|---|
+| Sidebar | Hidden (drawer) | Collapsed (icons only) | Full (240px) |
+| Stats cards | 2×2 grid | 4 in a row | 4 in a row |
+| Document grid | 1 column | 2 columns | 3 columns |
+| Login split | Single panel | Single panel | Split 40/60 |
+| Analytics charts | Stacked | Side by side | Side by side |
+---
+## 9. Accessibility
+- All interactive elements: `focus-visible` ring in `green-700` at 2px offset
+- Color contrast: all text meets WCAG AA (4.5:1 minimum)
+- Screen reader: `aria-label` on all icon-only buttons
+- Form inputs: `id`/`htmlFor` linked labels
+- Status badges: `role="status"` + `aria-live="polite"` for processing states
+- Modal: focus trap, `aria-modal="true"`, `Escape` key closes
+- Keyboard navigation: full tab order, sidebar navigable with arrow keys
+---
+## 10. Performance Requirements
+- Lighthouse score target: 90+ (Performance, Accessibility, Best Practices)
+- First Contentful Paint: < 1.5s
+- Images: next/image with lazy loading
+- Code splitting: automatic via Next.js App Router
+- Supabase queries: select only needed columns (never `select *`)
+- Analytics charts: lazy-loaded (only render when tab is visible)
+---
+## 11. Error States
+Every async action must handle three states: loading, success, error.
+| Scenario | UI Behaviour |
+|---|---|
+| Login fails — wrong password | Inline error below password field |
+| Login fails — no network | Toast: "Connection error. Check your internet." |
+| Upload — file too large | Inline error in drop zone before upload |
+| Upload — server error | Toast error + revert to Step 1 with retry button |
+| Document delete fails | Toast error, document remains in list |
+| Analytics load fails | Skeleton loaders replaced with "Could not load data" + retry |
+| n8n unreachable | Yellow warning banner at top: "AI backend is currently unavailable." |
+---
+## 12. Skeleton Loading States
+Every data-loaded section must show a skeleton before data arrives:
+- Stat cards: gray-200 rounded rectangles, `animation: pulse 1.5s ease-in-out infinite`
+- Table rows: alternating gray-100/gray-50 bars
+- Chart areas: gray-200 rounded rectangle same size as chart
+- Document cards: gray placeholder blocks
+```css
+@keyframes skeleton-pulse {
+  0%, 100% { opacity: 1; }
+  50%       { opacity: 0.5; }
+}
+.skeleton {
+  background: var(--gray-200);
+  border-radius: var(--radius-sm);
+  animation: skeleton-pulse 1.5s ease-in-out infinite;
+}
+```
+---
+*End of PRD — DriveSmart AI Instructor Dashboard v1.0*
+*Built for AA Kenya driving school branding. Ready for lovable.dev / v0.dev generation.*