# abubakrsiddikl/digital-wallet architecture

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

- Interactive diagram: https://gitdiagram.com/abubakrsiddikl/digital-wallet
- Repository: https://github.com/abubakrsiddikl/digital-wallet

## Overview

1. **Overall shape**
This is a two-app monorepo: a **Next.js 15 frontend** in `frontend/` and an **Express + Prisma backend** in `Backend/`. The backend owns all business rules and persistence; the frontend is a role-based UI for public pages plus authenticated dashboards for users, agents, and admins.

2. **Frontend boundary**
The frontend uses the **App Router** with route groups for `commonLayout` and `dashboardLayout`. Public marketing/auth pages live alongside protected dashboard areas, which are split by role into **user**, **agent**, and **admin** sections. This structure matters for diagramming because navigation and authorization are organized by layout boundaries rather than a single SPA shell.

3. **Backend boundary**
The backend is organized as a classic layered API: `routes -> controller -> service -> Prisma DB`. Each domain has its own module under `src/app/module/` such as `auth`, `user`, `wallet`, `transaction`, `agentApplication`, and `stats`. Cross-cutting middleware handles auth, not-found, and global errors, while utilities centralize response formatting, JWT handling, and Prisma access.

4. **Primary domain modules**
The core business domains are:
- **Auth**: login/register/OTP-related flows and cookie/token handling
- **User**: user profile and account management
- **Wallet**: balance and wallet operations
- **Transaction**: money movement and transaction history
- **Agent Application**: becoming an agent and balance requests
- **Stats**: aggregate dashboard metrics for admin and role-specific views  
These modules are the main system boundaries for both API endpoints and frontend screens.

5. **Data model and persistence**
Persistence is backed by **PostgreSQL** through **Prisma**. The Prisma schema is split into domain files such as `user.prisma`, `wallet.prisma`, `transaction.prisma`, `agentRequest.prisma`, and `agentBalanceRequest.prisma`, with migrations capturing the evolution of the wallet and transaction model. Architecturally, this implies a normalized relational core centered on users, wallets, and transaction records.

6. **Money movement flow**
Transaction-related flows are the central runtime path of the system. User actions like **send money, cash out, add money, and mobile recharge** originate in the frontend, hit the transaction/wallet APIs, and are validated and committed on the backend before the resulting balances and history are returned. The readme indicates fees and commissions are part of these flows, so transaction creation likely also updates wallet balances and commission-related records in one backend operation.

7. **Agent workflow**
Agent-related behavior is a separate branch of the business process. Users can **apply to become agents**, admins can approve/reject those applications, and agents can submit **balance requests** to top up their operating funds. The backend has dedicated `agentApplication` handling, while the frontend has dedicated user, agent, and admin pages for each stage of the workflow.

8. **Admin control plane**
The admin dashboard is a distinct subsystem, not just another set of screens. It exposes user management, agent management, agent application review, balance request review, system transactions, balance overview, commission settings, and audit logs. This implies a centralized operational control plane that reads from the same transactional data but exercises privileged state changes.

9. **Real-time messaging**
The repo includes a Socket.io layer on both sides: backend socket server/emitter/event definitions and frontend socket provider/hooks. Real-time events such as transaction success, balance updates, new agent applications, and balance request status changes are pushed to affected users and admins. In a diagram, this is a separate asynchronous channel alongside the request/response API.

10. **Frontend data access layer**
The frontend does not talk to the backend directly from UI components; it routes through a `services/` layer with domain-specific API clients for auth, user, stats, transaction, and agent application. Validation is handled with Zod schemas, and reusable hooks like `useSocket` and `useRealtimeData` support live updates. This makes the frontend architecture a clean split between page composition, reusable components, and API/service orchestration.

11. **Shared UI and layout composition**
The UI is heavily componentized into `components/modules/*`, `components/layout/*`, and `components/shared/*`. That split reflects three layers: page-specific business UI, shared shell/navigation, and reusable primitives. For architecture diagrams, the important point is that dashboard shells, role-based sidebars, and content modules are all separate, so the same data can be rendered under different user experiences.

12. **Operational utilities and deployment**
The backend includes `seedSystemWallet`, auth cookie helpers, pagination helpers, and a custom Prisma wrapper, which suggests operational concerns like bootstrapping system balances and standardizing API responses. The presence of `render-build.sh` and live Render URLs in the readme indicates deployment to **Render**, with the frontend and backend deployed as separate services and the frontend configured to call the backend API base URL.

13. **External dependencies that matter**
The architecture meaningfully depends on **Next.js**, **Express**, **Prisma**, **PostgreSQL**, and **Socket.io**. These are not incidental: Next.js shapes the frontend routing/layout model, Express provides the API boundary, Prisma owns data access and migrations, PostgreSQL is the durable transaction store, and Socket.io supplies cross-user live updates for state changes that matter immediately.

14. **How to draw the system**
A good diagram would place the **frontend app** on one side with three role-based dashboard branches, the **backend API** in the middle with module boundaries, **PostgreSQL/Prisma** beneath as the persistent store, and a **Socket.io realtime lane** connecting backend events to subscribed frontend sessions. The key flows to show are authentication, wallet/transaction mutations, agent application and balance request approval, and admin stats/oversight.

Main entry points: [`Backend/src/app/routes/index.ts`](https://github.com/abubakrsiddikl/digital-wallet/blob/main/Backend/src/app/routes/index.ts) (Route Index), [`Backend/src/app/module/transaction`](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/transaction) (Transaction Module), [`frontend/src/services`](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/services) (API Services), [`frontend/src/components`](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/components) (UI Modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Router<br/>Next.js 15 app"]
  node_frontend_public["Public Pages<br/>marketing/auth routes"]
  node_frontend_dash["Dashboards"]
  node_frontend_services["API Services<br/>client API layer"]
  node_frontend_components["UI Modules<br/>component system"]
  node_frontend_state["Form Schemas<br/>zod validation"]
end

subgraph group_backend["Backend"]
  node_backend_api["API Server<br/>Express entrypoint<br/>[server.ts]"]
  node_backend_routes["Route Index<br/>api composition<br/>[index.ts]"]
  node_backend_auth["Auth Module<br/>auth domain"]
  node_backend_user["User Module<br/>user domain"]
  node_backend_wallet["Wallet Module<br/>wallet domain"]
  node_backend_tx["Transaction Module<br/>money movement"]
  node_backend_agent["Agent Application<br/>agent workflow"]
  node_backend_stats["Stats Module<br/>dashboard metrics"]
  node_backend_mw["Middleware<br/>cross-cutting"]
  node_backend_utils["Utilities<br/>shared helpers"]
end

subgraph group_data["Data"]
  node_data_prisma["Prisma Schema<br/>domain schema"]
  node_data_migrations["Migrations<br/>schema history"]
  node_data_db[("PostgreSQL<br/>relational store")]
end

subgraph group_realtime["Realtime"]
  node_frontend_socket(("Socket Client<br/>realtime client"))
  node_backend_socket(("Socket Server<br/>realtime server"))
end

node_frontend_app -->|"routes"| node_frontend_public
node_frontend_app -->|"routes"| node_frontend_dash
node_frontend_public -->|"calls"| node_frontend_services
node_frontend_dash -->|"renders"| node_frontend_components
node_frontend_components -->|"uses"| node_frontend_services
node_frontend_state -->|"validates"| node_frontend_components
node_frontend_socket -->|"updates"| node_frontend_components
node_frontend_socket -->|"syncs"| node_frontend_services
node_backend_api -->|"mounts"| node_backend_routes
node_backend_routes -->|"exposes"| node_backend_auth
node_backend_routes -->|"exposes"| node_backend_user
node_backend_routes -->|"exposes"| node_backend_wallet
node_backend_routes -->|"exposes"| node_backend_tx
node_backend_routes -->|"exposes"| node_backend_agent
node_backend_routes -->|"exposes"| node_backend_stats
node_backend_auth -->|"guards"| node_backend_mw
node_backend_user -->|"uses"| node_backend_utils
node_backend_wallet -->|"uses"| node_backend_utils
node_backend_tx -->|"updates"| node_backend_wallet
node_backend_tx -->|"emits"| node_backend_socket
node_backend_agent -->|"emits"| node_backend_socket
node_backend_stats -->|"broadcasts"| node_backend_socket
node_backend_utils -->|"reads/writes"| node_data_prisma
node_data_prisma -->|"maps to"| node_data_db
node_data_migrations -->|"evolves"| node_data_db
node_backend_socket -->|"pushes events"| node_frontend_socket
node_frontend_services -->|"api calls"| node_backend_api
node_backend_tx -->|"persists"| node_data_prisma
node_backend_agent -->|"persists"| node_data_prisma

click node_frontend_app "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/app"
click node_frontend_public "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/app/(commonLayout)"
click node_frontend_dash "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/app/(dashboardLayout)"
click node_frontend_services "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/services"
click node_frontend_components "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/components"
click node_frontend_socket "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/socket"
click node_frontend_state "https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/zodSchema"
click node_backend_api "https://github.com/abubakrsiddikl/digital-wallet/blob/main/Backend/src/server.ts"
click node_backend_routes "https://github.com/abubakrsiddikl/digital-wallet/blob/main/Backend/src/app/routes/index.ts"
click node_backend_auth "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/auth"
click node_backend_user "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/user"
click node_backend_wallet "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/wallet"
click node_backend_tx "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/transaction"
click node_backend_agent "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/agentApplication"
click node_backend_stats "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/stats"
click node_backend_mw "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/middleware"
click node_backend_utils "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/utils"
click node_backend_socket "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/socket"
click node_data_prisma "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/prisma/schema"
click node_data_migrations "https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/prisma/migrations"

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_frontend_app,node_frontend_public,node_frontend_dash,node_frontend_services,node_frontend_components,node_frontend_state toneBlue
class node_backend_api,node_backend_routes,node_backend_auth,node_backend_user,node_backend_wallet,node_backend_tx,node_backend_agent,node_backend_stats,node_backend_mw,node_backend_utils toneAmber
class node_data_prisma,node_data_migrations,node_data_db toneMint
class node_frontend_socket,node_backend_socket toneRose
```

## Components

### Frontend

Next.js App Router UI with public pages and role-based dashboards.

- [App Router](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/app): Next.js 15 app · Route-grouped public and authenticated pages. · `frontend/src/app`
- [Public Pages](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/app/(commonLayout)): marketing/auth routes · Landing, pricing, about, contact, login, register, OTP, and password recovery. · `frontend/src/app/(commonLayout)`
- [Dashboards](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/app/(dashboardLayout)): role dashboards · Protected user, agent, and admin dashboard branches under a shared layout. · `frontend/src/app/(dashboardLayout)`
- [API Services](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/services): client API layer · Domain-specific clients for auth, user, stats, transaction, and agent application. · `frontend/src/services`
- [UI Modules](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/components): component system · Layout, shared, and domain modules for page composition and role-based screens. · `frontend/src/components`
- [Form Schemas](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/zodSchema): zod validation · Client-side validation schemas for auth, transaction, and agent application flows. · `frontend/src/zodSchema`

### Backend

Express API with layered domain modules and middleware.

- [API Server](https://github.com/abubakrsiddikl/digital-wallet/blob/main/Backend/src/server.ts): Express entrypoint · Server bootstrap and route wiring for the backend application. · `Backend/src/server.ts`
- [Route Index](https://github.com/abubakrsiddikl/digital-wallet/blob/main/Backend/src/app/routes/index.ts): api composition · Mounts domain routers under the backend API boundary. · `Backend/src/app/routes/index.ts`
- [Auth Module](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/auth): auth domain · Login, register, OTP, JWT, and cookie/session handling. · `Backend/src/app/module/auth`
- [User Module](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/user): user domain · Profile and account management APIs. · `Backend/src/app/module/user`
- [Wallet Module](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/wallet): wallet domain · Balance and wallet operations. · `Backend/src/app/module/wallet`
- [Transaction Module](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/transaction): money movement · Send money, cash out, add money, recharge, and transaction history. · `Backend/src/app/module/transaction`
- [Agent Application](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/agentApplication): agent workflow · Agent application and balance request handling. · `Backend/src/app/module/agentApplication`
- [Stats Module](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/module/stats): dashboard metrics · Aggregate metrics for admin and role-specific dashboards. · `Backend/src/app/module/stats`
- [Middleware](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/middleware): cross-cutting · Auth guard, not-found, and global error handling. · `Backend/src/app/middleware`
- [Utilities](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/utils): shared helpers · Prisma wrapper, JWT helpers, response formatting, pagination, cookies, and seeding. · `Backend/src/app/utils`

### Data

Prisma schema, migrations, and PostgreSQL-backed persistence.

- [Prisma Schema](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/prisma/schema): domain schema · Split schema files for users, wallets, transactions, and agent requests. · `Backend/prisma/schema`
- [Migrations](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/prisma/migrations): schema history · Database evolution for wallet, transaction, and agent request models. · `Backend/prisma/migrations`
- **PostgreSQL**: relational store · Durable storage for users, wallets, transactions, commissions, and requests.

### Realtime

Socket.io event lane for live updates and notifications.

- [Socket Client](https://github.com/abubakrsiddikl/digital-wallet/tree/main/frontend/src/socket): realtime client · Socket provider, hooks, and notification context for live UI updates. · `frontend/src/socket`
- [Socket Server](https://github.com/abubakrsiddikl/digital-wallet/tree/main/Backend/src/app/socket): realtime server · Socket.io server, emitter, and event definitions for backend push events. · `Backend/src/app/socket`

## Connections

- App Router → Public Pages: routes · Public marketing and authentication pages live in the common layout.
- App Router → Dashboards: routes · Protected dashboard branches are grouped by role.
- Public Pages → API Services: calls · Auth-facing pages submit through API clients.
- Dashboards → UI Modules: renders · Role dashboards compose shared and domain-specific UI modules.
- UI Modules → API Services: uses · Forms and dashboards fetch and mutate through service clients.
- Form Schemas → UI Modules: validates · Component forms use Zod schemas for input validation.
- Socket Client → UI Modules: updates · Live notifications and dashboard state feed UI modules.
- Socket Client → API Services: syncs · Realtime events complement API-driven data refreshes.
- API Server → Route Index: mounts · Server entrypoint wires the route index.
- Route Index → Auth Module: exposes · Auth endpoints are registered as a domain router.
- Route Index → User Module: exposes · User endpoints are registered as a domain router.
- Route Index → Wallet Module: exposes · Wallet endpoints are registered as a domain router.
- Route Index → Transaction Module: exposes · Transaction endpoints are registered as a domain router.
- Route Index → Agent Application: exposes · Agent workflow endpoints are registered as a domain router.
- Route Index → Stats Module: exposes · Stats endpoints are registered as a domain router.
- Auth Module → Middleware: guards · Auth flows rely on shared middleware and cookie/JWT helpers.
- User Module → Utilities: uses · User flows use response, pagination, and database helpers.
- Wallet Module → Utilities: uses · Wallet operations rely on shared persistence utilities.
- Transaction Module → Wallet Module: updates · Money movement mutates wallet balances as part of commits.
- Transaction Module → Socket Server: emits · Transaction outcomes push realtime events to clients.
- Agent Application → Socket Server: emits · Application and balance-request changes notify subscribers.
- Stats Module → Socket Server: broadcasts · Dashboard metrics and operational changes can be pushed live.
- Utilities → Prisma Schema: reads/writes · Prisma wrapper centralizes database access.
- Prisma Schema → PostgreSQL: maps to · Schema defines the PostgreSQL data model.
- Migrations → PostgreSQL: evolves · Migrations apply schema changes to the database.
- Socket Server → Socket Client: pushes events · Backend socket events reach subscribed frontend sessions.
- API Services → API Server: api calls · Frontend service clients talk to the backend API.
- Transaction Module → Prisma Schema: persists · Transactions are validated and committed through Prisma.
- Agent Application → Prisma Schema: persists · Agent applications and balance requests are stored via Prisma.