noblepay/web-app

1. Repository shape

This repo is split into two main areas: a documentation-heavy noblepay-docs folder that describes the target system, and the actual application code under shadcn-ui. The runtime architecture is centered on a React frontend plus a Node/Express backend.

2. Frontend application boundary

The main user-facing app is a Vite + React + TypeScript single-page application in shadcn-ui/src. It uses shadcn/ui component primitives, Tailwind styling, and page-level screens for Index, Login, AuthCallback, BillPayment, MobileRecharge, and Remittance.

3. Feature-oriented UI structure

The UI is organized by business capability rather than by technical layer. There are dedicated component groups for bill payment, mobile recharge, and remittance, alongside top-level marketing/navigation sections like Hero, Header, Footer, and feature overview sections such as PaymentsSection and MarketplaceSection.

4. Client-side auth and route protection

Authentication is handled on the frontend through Supabase client/auth wrappers and a ProtectedRoute component. The UI has a clear auth boundary: unauthenticated users go through login and callback flow, while protected business views depend on an established session.

5. Backend API layer

The backend is an Express-based API in shadcn-ui/backend/src with route modules for auth, accounts, bills, countries, marketplace, mobileMoney, payments, remittance, transactions, and users. This is the main server-side boundary that the frontend calls for business operations.

6. Server-side security boundary

The backend includes an auth middleware, which suggests route-level access control and token/session validation. That makes the API the enforcement point for protected operations, separate from the frontend’s visual route gating.

7. Persistence and data model

Data storage is handled through Prisma with a SQLite database (prisma/noblepay.db) and migration history in prisma/migrations. The schema.prisma file is the canonical model definition for accounts, transactions, and related domain entities.

8. Domain flow by business capability

The main functional flows map directly to the API and UI modules: payments/bills, mobile money recharge, remittance, and general account/transaction management. Supporting modules like countries and marketplace likely provide reference data and partner/service catalogs used by those flows.

9. Integration and state management

Frontend-side integration lives in lib/api-client.ts, lib/supabase.ts, and lib/supabase-hooks.ts, which act as the bridge between React views and backend/auth services. This is where request/response handling and session-aware data access are centralized.

10. Infrastructure and supporting artifacts

The repo includes CI via .github/workflows/npm-grunt.yml, static assets under public, and a uploads directory containing a strategic-plan PDF. These are supporting pieces; they do not define the core runtime architecture.

11. Important duplication note

There are duplicated nested copies of backend and Supabase-related files under shadcn-ui/shadcn-ui/backend and shadcn-ui/backend/backend. For diagramming, treat the architecture as one frontend app plus one main Express/Prisma backend, with the nested copies appearing to be mirrored or generated artifacts rather than separate product subsystems.

12. Best diagram boundaries

A clear architecture diagram should show: user/browser → React SPA → Supabase auth/session layer and/or Express API → Prisma/SQLite persistence. Around that core, the major domain services are bill payment, mobile recharge, remittance, accounts, transactions, and reference-data lookups.