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