# Implementation Plan: Complete TenderHub Kenya

## Goal
Fix correctness issues and build the complete user-facing frontend to replace the developer console. This transforms the working backend into a shippable product.

## Scope & Prioritization

The backend is ~95% complete and well-built. The work falls into two categories:

### A. Fix Correctness Issues (Small)
1. Wire Supabase Auth (real login/signup, replace header stubs)
2. Wire observability (`initMonitoring()` in layout)
3. Fix deprecated Sentry `startTransaction` API

### B. Build User-Facing UI (Large)  
4. Complete mobile-first dashboard with premium design
5. PWA manifest + basic service worker

> [!IMPORTANT]
> The existing developer console (`page.tsx`) will be preserved at `/console` for debugging. The new user-facing UI will be the default at `/`.

---

## User Review Required

> [!WARNING]
> **Auth approach**: The current system uses `x-org-id`/`x-user-id` headers. The plan replaces this with real Supabase Auth for user-facing pages while keeping the dev header fallback for API testing. This is a non-breaking change.

> [!IMPORTANT]
> **UI scope**: Building a full production UI is substantial. This plan covers all core user flows: signup → profile setup → upload → processing → preview → payment → analysis → drafts → DOCX download. The design will be mobile-first, dark-mode capable, with premium aesthetics.

---

## Proposed Changes

### Component 1: Supabase Auth Integration

#### [NEW] [supabase-browser.ts](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/lib/supabase/browser.ts)
- Create browser-side Supabase client using `createBrowserClient` from `@supabase/ssr`
- Uses `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY`

#### [NEW] [supabase-server.ts](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/lib/supabase/server.ts)
- Create server-side Supabase client using cookies for SSR auth
- Used by server components and API routes

#### [NEW] [AuthProvider.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/AuthProvider.tsx)
- React context provider for auth state
- Listens to `onAuthStateChange`
- Provides `user`, `session`, `signOut`, `loading` state

#### [MODIFY] [request-identity.ts](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/lib/request-identity.ts)
- Keep existing header-based fallback for dev/testing
- Prioritize cookie-based Supabase session when available
- Add `resolveRequestIdentityFromCookies()` helper

#### [NEW] [middleware.ts](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/middleware.ts)
- Next.js middleware to protect routes
- Redirect unauthenticated users to `/login`
- Allow public access to `/`, `/login`, `/signup`, `/api/payments/mpesa/callback`

---

### Component 2: Auth Pages

#### [NEW] [login/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/login/page.tsx)
- Email/password login form
- Magic link option
- Link to signup
- Premium glassmorphism design

#### [NEW] [signup/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/signup/page.tsx)
- Email/password signup
- Auto-create organization + membership on first login
- Redirect to onboarding/profile setup

#### [NEW] [auth/callback/route.ts](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/auth/callback/route.ts)
- OAuth/magic link callback handler

---

### Component 3: Design System & Layout

#### [MODIFY] [globals.css](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/globals.css)
- Complete redesign with premium design system
- CSS custom properties for dark/light themes
- Mobile-first responsive grid
- Glassmorphism effects, smooth transitions
- Typography using Inter font from Google Fonts
- Component styles: cards, badges, modals, progress indicators, tabs

#### [MODIFY] [layout.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/layout.tsx)
- Add Google Fonts (Inter)
- Add AuthProvider wrapper
- Add viewport meta for mobile
- Call `initMonitoring()` via client component
- Add PWA manifest link

---

### Component 4: Dashboard Pages

#### [MODIFY] [page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/page.tsx) → Landing/Marketing Page
- Replace developer console with a landing page
- Hero section explaining the product
- CTA to signup/login

#### [NEW] [console/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/console/page.tsx)
- Move existing developer console here

#### [NEW] [dashboard/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/dashboard/page.tsx)
- Main authenticated dashboard
- Tender list with status badges
- Upload button prominent
- Quick stats (total tenders, pending, analyzed)
- Recent activity feed

#### [NEW] [dashboard/layout.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/dashboard/layout.tsx)
- Shared dashboard layout with sidebar/nav
- Mobile hamburger menu
- User avatar + signout

#### [NEW] [dashboard/upload/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/dashboard/upload/page.tsx)
- Drag-and-drop PDF upload zone
- File validation (PDF only, size limit)
- Upload progress bar
- Auto-redirect to tender detail after upload

#### [NEW] [dashboard/tenders/[id]/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/dashboard/tenders/[id]/page.tsx)
- Tender detail page with tabbed interface:
  - **Overview tab**: Status, procuring entity, deadline, category
  - **Compliance tab**: Compliance matrix with pass/fail/unknown indicators
  - **Score tab**: Bid/no-bid score visualization with gauges
  - **Drafts tab**: Generated draft sections with edit capability
  - **Download tab**: DOCX export button
- Real-time status polling during processing
- Payment unlock flow inline

#### [NEW] [dashboard/profile/page.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/app/dashboard/profile/page.tsx)
- Company profile form
- All fields from CompanyProfile schema
- Save/update via API

---

### Component 5: UI Components

#### [NEW] [components/Navbar.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/Navbar.tsx)
- Top navigation bar
- Logo, nav links, user menu
- Mobile responsive

#### [NEW] [components/TenderCard.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/TenderCard.tsx)
- Tender list card with status badge, filename, date
- Click to navigate to detail

#### [NEW] [components/ComplianceMatrix.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/ComplianceMatrix.tsx)
- Visual compliance checklist
- Color-coded severity (CRITICAL=red, HIGH=orange, MEDIUM=yellow, LOW=green)
- Pass/Fail/Unknown status indicators

#### [NEW] [components/BidScoreGauge.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/BidScoreGauge.tsx)
- Circular/arc score gauge (0-100)
- BID (green), NO_BID (red), REVIEW (amber)
- Animated on load

#### [NEW] [components/UploadZone.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/UploadZone.tsx)
- Drag-and-drop file upload area
- PDF validation
- Progress indicator
- Actual file upload to signed URL

#### [NEW] [components/ProcessingStatus.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/ProcessingStatus.tsx)
- Real-time job status with polling
- Step indicator (Upload → Processing → Preview → Analysis)
- Error state with retry button

#### [NEW] [components/PaymentModal.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/PaymentModal.tsx)
- M-Pesa payment flow
- Phone number input
- STK push initiation
- Payment status polling
- Success/failure states

#### [NEW] [components/DraftViewer.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/DraftViewer.tsx)
- Section-by-section draft viewer
- Editable text areas
- Generate/regenerate buttons
- DOCX export button

#### [NEW] [components/MonitoringInit.tsx](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/components/MonitoringInit.tsx)
- Client component that calls `initMonitoring()` on mount
- Identifies user when auth state changes

---

### Component 6: Monitoring Fixes

#### [MODIFY] [monitoring/index.ts](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/src/lib/monitoring/index.ts)
- Remove deprecated `startTransaction` API
- Use safe no-op pattern for when Sentry/PostHog aren't installed
- Keep the rest working as-is

---

### Component 7: PWA

#### [NEW] [public/manifest.json](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/public/manifest.json)
- PWA manifest with app name, icons, theme color
- `display: standalone` for mobile

#### [NEW] [public/sw.js](file:///c:/Users/Angelah/Documents/TenderHubKenya/apps/web/public/sw.js)
- Basic service worker for offline caching
- Cache static assets and API responses
- Network-first strategy for API calls

---

## Open Questions

> [!IMPORTANT]
> **No blocking questions.** The build plan and existing codebase provide clear direction. I will proceed with the implementation as described above.

---

## Verification Plan

### Automated Tests
- `npm run build` — verify the app compiles without errors
- `npm run typecheck` — verify TypeScript types
- Start dev server and verify all routes load

### Manual Verification
- Navigate through the full user flow in the browser:
  1. Landing page loads with premium design
  2. Login/signup works
  3. Dashboard shows tender list
  4. Upload a PDF
  5. Processing status updates in real-time
  6. Preview shows extracted info
  7. Payment modal triggers STK push
  8. Analysis page shows compliance matrix and bid score
  9. Draft generation and DOCX export work
  10. Mobile responsive at 375px width