# noblepay/web-app architecture

> Architecture diagram of the GitHub repository noblepay/web-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noblepay/web-app
- Repository: https://github.com/noblepay/web-app

## Overview

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.

Main entry points: [`shadcn-ui/backend/server.js`](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/server.js) (API server), [`shadcn-ui/backend/prisma/schema.prisma`](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/prisma/schema.prisma) (Prisma schema), [`shadcn-ui/src/main.tsx`](https://github.com/noblepay/web-app/blob/main/shadcn-ui/src/main.tsx) (App shell), [`shadcn-ui/src/pages`](https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/pages) (Screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_docs_overview["Docs set<br/>documentation"]
end

subgraph group_frontend["Frontend"]
  node_spa_shell["App shell<br/>vite-react app<br/>[main.tsx]"]
  node_screens["Screens<br/>page routes"]
  node_feature_sections["Feature UI<br/>domain components"]
  node_business_forms["Flow forms<br/>transaction UI"]
  node_ui_kit["UI kit<br/>shadcn primitives"]
end

subgraph group_backend["Backend"]
  node_api_server["API server<br/>express app<br/>[server.js]"]
  node_api_auth["API auth<br/>middleware<br/>[auth.js]"]
  node_account_routes["Account API<br/>domain routes<br/>[accounts.js]"]
  node_payment_routes["Payment API<br/>domain routes<br/>[payments.js]"]
  node_market_routes["Reference API<br/>lookup routes<br/>[countries.js]"]
  node_remit_routes["Remittance API<br/>domain routes<br/>[remittance.js]"]
end

subgraph group_data["Data"]
  node_schema["Prisma schema<br/>data model<br/>[schema.prisma]"]
  node_migrations["Migrations<br/>schema history"]
  node_sqlite_db[("SQLite DB<br/>storage<br/>[noblepay.db]")]
end

subgraph group_support["Support"]
  node_auth_ui["Auth UI<br/>session boundary"]
  node_client_api["API client<br/>frontend integration<br/>[api-client.ts]"]
  node_supabase_client["Supabase client<br/>auth/session<br/>[supabase.ts]"]
end

node_docs_overview -.->|"describes"| node_spa_shell
node_docs_overview -.->|"describes"| node_api_server
node_spa_shell -->|"routes to"| node_screens
node_spa_shell -->|"composes"| node_feature_sections
node_spa_shell -->|"wraps"| node_auth_ui
node_screens -->|"uses"| node_business_forms
node_screens -->|"guards"| node_auth_ui
node_feature_sections -->|"builds on"| node_ui_kit
node_business_forms -->|"builds on"| node_ui_kit
node_auth_ui -->|"authenticates with"| node_supabase_client
node_client_api -->|"calls"| node_api_server
node_client_api -->|"shares session"| node_supabase_client
node_api_server -->|"enforces"| node_api_auth
node_api_server -->|"mounts"| node_account_routes
node_api_server -->|"mounts"| node_payment_routes
node_api_server -->|"mounts"| node_market_routes
node_api_server -->|"mounts"| node_remit_routes
node_account_routes -->|"reads/writes"| node_schema
node_payment_routes -->|"reads/writes"| node_schema
node_remit_routes -->|"reads/writes"| node_schema
node_market_routes -->|"reads"| node_schema
node_schema -->|"evolves via"| node_migrations
node_schema -->|"persists to"| node_sqlite_db
node_migrations -->|"applies to"| node_sqlite_db

click node_docs_overview "https://github.com/noblepay/web-app/tree/main/noblepay-docs"
click node_spa_shell "https://github.com/noblepay/web-app/blob/main/shadcn-ui/src/main.tsx"
click node_screens "https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/pages"
click node_feature_sections "https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components"
click node_business_forms "https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components/bill-payment"
click node_auth_ui "https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components/auth"
click node_client_api "https://github.com/noblepay/web-app/blob/main/shadcn-ui/lib/api-client.ts"
click node_supabase_client "https://github.com/noblepay/web-app/blob/main/shadcn-ui/src/lib/supabase.ts"
click node_ui_kit "https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components/ui"
click node_api_server "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/server.js"
click node_api_auth "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/middleware/auth.js"
click node_account_routes "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/accounts.js"
click node_payment_routes "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/payments.js"
click node_market_routes "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/countries.js"
click node_remit_routes "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/remittance.js"
click node_schema "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/prisma/schema.prisma"
click node_migrations "https://github.com/noblepay/web-app/tree/main/shadcn-ui/backend/prisma/migrations"
click node_sqlite_db "https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/prisma/noblepay.db"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_docs_overview toneBlue
class node_spa_shell,node_screens,node_feature_sections,node_business_forms,node_ui_kit toneAmber
class node_api_server,node_api_auth,node_account_routes,node_payment_routes,node_market_routes,node_remit_routes toneMint
class node_schema,node_migrations,node_sqlite_db toneRose
class node_auth_ui,node_client_api,node_supabase_client toneIndigo
```

## Components

### Docs

Architecture and product documentation

- [Docs set](https://github.com/noblepay/web-app/tree/main/noblepay-docs): documentation · System and product documentation in noblepay-docs · `noblepay-docs`

### Frontend

React SPA and UI composition

- [App shell](https://github.com/noblepay/web-app/blob/main/shadcn-ui/src/main.tsx): vite-react app · Frontend entrypoints and route composition · `shadcn-ui/src/main.tsx`
- [Screens](https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/pages): page routes · Top-level pages for index, login, auth callback, and business flows · `shadcn-ui/src/pages`
- [Feature UI](https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components): domain components · Hero, header/footer, payments, bills, mobile money, and remittance sections · `shadcn-ui/src/components`
- [Flow forms](https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components/bill-payment): transaction UI · Bill payment, recharge, and remittance forms and trackers · `shadcn-ui/src/components/bill-payment`
- [UI kit](https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components/ui): shadcn primitives · Reusable UI primitives used across the app · `shadcn-ui/src/components/ui`

### Backend

Express API and domain routes

- [API server](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/server.js): express app · Node/Express server entrypoint and middleware wiring · `shadcn-ui/backend/server.js`
- [API auth](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/middleware/auth.js): middleware · Server-side access control and token/session validation · `shadcn-ui/backend/src/middleware/auth.js`
- [Account API](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/accounts.js): domain routes · Accounts, users, and transactions endpoints · `shadcn-ui/backend/src/routes/accounts.js`
- [Payment API](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/payments.js): domain routes · Bills, payments, and mobile money endpoints · `shadcn-ui/backend/src/routes/payments.js`
- [Reference API](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/countries.js): lookup routes · Countries and marketplace reference endpoints · `shadcn-ui/backend/src/routes/countries.js`
- [Remittance API](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/src/routes/remittance.js): domain routes · Remittance-specific endpoints · `shadcn-ui/backend/src/routes/remittance.js`

### Data

Prisma schema, migrations, and SQLite storage

- [Prisma schema](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/prisma/schema.prisma): data model · Canonical domain model for accounts, transactions, and related entities · `shadcn-ui/backend/prisma/schema.prisma`
- [Migrations](https://github.com/noblepay/web-app/tree/main/shadcn-ui/backend/prisma/migrations): schema history · Database migration history · `shadcn-ui/backend/prisma/migrations`
- [SQLite DB](https://github.com/noblepay/web-app/blob/main/shadcn-ui/backend/prisma/noblepay.db): storage · Local persistent datastore · `shadcn-ui/backend/prisma/noblepay.db`

### Support

Shared auth and integration layers

- [Auth UI](https://github.com/noblepay/web-app/tree/main/shadcn-ui/src/components/auth): session boundary · Protected route and Supabase auth provider for client-side gating · `shadcn-ui/src/components/auth`
- [API client](https://github.com/noblepay/web-app/blob/main/shadcn-ui/lib/api-client.ts): frontend integration · Typed client bridge to backend services · `shadcn-ui/lib/api-client.ts`
- [Supabase client](https://github.com/noblepay/web-app/blob/main/shadcn-ui/src/lib/supabase.ts): auth/session · Supabase helpers and hooks used by the SPA · `shadcn-ui/src/lib/supabase.ts`

## Connections

- Docs set → App shell: describes · Documentation defines the intended application structure
- Docs set → API server: describes · Documentation also covers backend and deployment architecture
- App shell → Screens: routes to · App shell renders page-level screens
- App shell → Feature UI: composes · Main app assembles marketing and business sections
- App shell → Auth UI: wraps · Client session gating surrounds protected views
- Screens → Flow forms: uses · Business pages embed transaction-specific forms and trackers
- Screens → Auth UI: guards · Login and callback flow feed protected routes
- Feature UI → UI kit: builds on · Sections are implemented with shared UI primitives
- Flow forms → UI kit: builds on · Forms and panels use shared shadcn components
- Auth UI → Supabase client: authenticates with · Auth provider and protected routes use Supabase session helpers
- API client → API server: calls · Frontend API client sends requests to the backend
- API client → Supabase client: shares session · Client requests are session-aware through Supabase helpers
- API server → API auth: enforces · Express server applies auth middleware to protected operations
- API server → Account API: mounts · Server exposes account and transaction routes
- API server → Payment API: mounts · Server exposes payment and bill-payment routes
- API server → Reference API: mounts · Server exposes lookup and marketplace routes
- API server → Remittance API: mounts · Server exposes remittance routes
- Account API → Prisma schema: reads/writes · Account and transaction routes persist through Prisma models
- Payment API → Prisma schema: reads/writes · Payment workflows are backed by the domain schema
- Remittance API → Prisma schema: reads/writes · Remittance workflows persist through the schema
- Reference API → Prisma schema: reads · Reference-data endpoints derive from stored models
- Prisma schema → Migrations: evolves via · Schema changes are tracked by migrations
- Prisma schema → SQLite DB: persists to · Prisma schema maps onto the SQLite database
- Migrations → SQLite DB: applies to · Migration history shapes the database file