Skip to main content

05 — The frontend apps

There are six Next.js apps under apps/. Five are product frontends. The sixth is a Docusaurus stub.

Brutally honest summary: every product frontend is a polished UI shell with hardcoded mock data in src/data/*.ts. None call the API. None implement real auth flow against /api/auth/*. None handle errors, loading states, retries, or API contract versioning. Wiring them to the backend is Planned and will be substantial work per app.

Why this matters for you​

If you're a frontend engineer joining the team:

  • The route trees, layouts, components and design language are real and reviewable. They show intent.
  • The data layer is not real. You will be writing the fetch-and-state-management layer largely from scratch.
  • There is no shared API client. Adding @tanstack/react-query or similar is on the table; pick once the auth flow + endpoint shapes are confirmed.
  • The frontends share packages/shared/ui — 2,624 LOC of components, no tests, 73 import points. Test coverage is Planned (Phase 1 of the intern programme).

The five product apps​

apps/admin-web — DemozPay platform admin​

  • Port: 4200
  • Audience: Internal staff at DemozPay (operations, support, compliance, finance, KYC reviewers).
  • Status: Partial — UI shell Live, API integration Planned
  • Pages: 36 — dashboard, businesses, compliance, loans, EWA, BNPL, equb, remittance, notifications, users.
  • Real backend it would call: /api/business/*, /api/employees/*, future /api/admin/* endpoints.
  • What you can do today: navigate the UI; data is mock.

apps/employer-web — employer / HR / finance​

  • Port: 4201
  • Audience: HR managers, finance managers, business owners at client companies.
  • Status: Partial — UI shell Live, API integration Planned
  • Pages: 29 — dashboard, payroll, employees, compliance, integrations, reports.
  • Real backend it would call: /api/business/*, /api/employees/*, future /api/payroll/*.
  • What you can do today: navigate the UI; data is mock.

apps/employee-web — the end user​

  • Port: 4202
  • Audience: salary workers using DemozPay through their employer.
  • Status: Partial — UI shell Live, API integration Planned
  • Pages: 13 — login, onboarding, home, budget, activity, loans, EWA, settings.
  • Real backend it would call: /api/auth/* (sign-up, OTP, sign-in), /api/ewa/*, /api/loans/*, future /api/wallet/*.
  • What you can do today: navigate the UI; auth context is a client-side stub (uses localStorage, never hits the API).

apps/fi-web — financial institution / partner bank​

  • Port: 4203
  • Audience: partner FIs / MFIs viewing loans, reconciliation, settlements.
  • Status: Planned (backend); UI shell Partial
  • Pages: 10 — dashboard, integrations, reports, risk, loans.
  • Real backend it would call: future /api/fi/* (not yet defined).

apps/merchant-web — BNPL merchants​

  • Port: 4204
  • Audience: merchants accepting BNPL payments.
  • Status: Planned end-to-end; UI shell Partial
  • Pages: 9 — dashboard, transactions, reports, settlements, payout.
  • Real backend it would call: future /api/bnpl/* (no BNPL domain exists in code).

apps/docs-web — Docusaurus​

  • Port: 4205
  • Audience: external developers / integration partners.
  • Status: Stub — Docusaurus default template; no DemozPay content.
  • Recommendation: either fill with real partner / API docs or delete. Pure overhead today.

E2E tests (apps/*-e2e)​

Each product app has a paired *-e2e/ folder with Playwright. Today each contains a single template test (expect(page).toHaveTitle(...)). Real user-journey tests are Planned.

What an "API integration" sprint actually requires​

When the time comes to connect any of these to the backend, you'll need to settle:

  1. API client library. Likely @tanstack/react-query for server-state caching + retries. The OpenAPI generator (packages/contracts/openapi/) is Planned but not yet producing TS clients.
  2. Auth flow. better-auth has both @better-auth/react (client helpers) and supports plain cookie-based fetch. Pick one.
  3. Error handling & loading states. Currently nonexistent in any app.
  4. Tenant / org switching. Multi-org users need a /api/auth/ organization/set-active call before any tenant-scoped request.
  5. Token / cookie storage. better-auth uses HTTP-only cookies by default — works with Next.js server components, requires credentials: 'include' on fetch in client components.
  6. Type safety end-to-end. Without generated clients, expect manual type duplication between API DTOs and frontend types.

This is at least one focused sprint per app and probably more. Estimate accordingly when planning.

Continue reading​

Next: 06-status-matrix.md — the honest matrix of what's built.