How abubakrsiddikl/digital-wallet works
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: index.ts Route Index · transaction Transaction Module · services API Services · components UI Modules
Components 21
Frontend
Next.js App Router UI with public pages and role-based dashboards.
- App Router · Route-grouped public and authenticated pages.
frontend/src/app - Public Pages · Landing, pricing, about, contact, login, register, OTP, and password recovery.
frontend/src/app/(commonLayout) - Dashboards · Protected user, agent, and admin dashboard branches under a shared layout.
frontend/src/app/(dashboardLayout) - API Services · Domain-specific clients for auth, user, stats, transaction, and agent application.
frontend/src/services - UI Modules · Layout, shared, and domain modules for page composition and role-based screens.
frontend/src/components - Form Schemas · 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 · Server bootstrap and route wiring for the backend application.
Backend/src/server.ts - Route Index · Mounts domain routers under the backend API boundary.
Backend/src/app/routes/index.ts - Auth Module · Login, register, OTP, JWT, and cookie/session handling.
Backend/src/app/module/auth - User Module · Profile and account management APIs.
Backend/src/app/module/user - Wallet Module · Balance and wallet operations.
Backend/src/app/module/wallet - Transaction Module · Send money, cash out, add money, recharge, and transaction history.
Backend/src/app/module/transaction - Agent Application · Agent application and balance request handling.
Backend/src/app/module/agentApplication - Stats Module · Aggregate metrics for admin and role-specific dashboards.
Backend/src/app/module/stats - Middleware · Auth guard, not-found, and global error handling.
Backend/src/app/middleware - Utilities · Prisma wrapper, JWT helpers, response formatting, pagination, cookies, and seeding.
Backend/src/app/utils
Data
Prisma schema, migrations, and PostgreSQL-backed persistence.
- Prisma Schema · Split schema files for users, wallets, transactions, and agent requests.
Backend/prisma/schema - Migrations · Database evolution for wallet, transaction, and agent request models.
Backend/prisma/migrations - PostgreSQL · Durable storage for users, wallets, transactions, commissions, and requests.
Realtime
Socket.io event lane for live updates and notifications.
- Socket Client · Socket provider, hooks, and notification context for live UI updates.
frontend/src/socket - Socket Server · Socket.io server, emitter, and event definitions for backend push events.
Backend/src/app/socket
Connections 29
- 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.