# adir-jscode/walletxpress-api architecture

> Architecture diagram of the GitHub repository adir-jscode/walletxpress-api, 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/adir-jscode/walletxpress-api
- Repository: https://github.com/adir-jscode/walletxpress-api

## Overview

1. **What this repo is**
   - A TypeScript/Express backend for a digital wallet platform.
   - The source of truth is in `src/`; `dist/` is the compiled JavaScript build artifact for deployment/runtime.
   - The app is organized as a modular monolith: one API process, multiple feature modules, shared middleware, and shared infrastructure utilities.

2. **Runtime and entry points**
   - `src/server.ts` is the process entry point.
   - `src/app.ts` builds the Express application, applies middleware, mounts routes, and likely initializes sockets.
   - `src/app/routes/index.ts` acts as the route composition layer that wires feature routers under the API prefix.
   - `src/app/socket/socketManager.ts` is a separate integration point for realtime events.

3. **Core architectural pattern**
   - Each domain is split into `controller`, `service`, `route`, and where needed `model`, `validation`, and `interface`.
   - Controllers are the HTTP adapter layer.
   - Services hold business rules and transactional logic.
   - Routes define endpoint grouping and attach middleware.
   - This keeps request handling, domain logic, and persistence concerns separated.

4. **Main feature boundaries**
   - `auth`: login, token refresh, logout, password change/reset.
   - `user`: registration and admin-facing user/agent listings.
   - `otp`: email-based OTP sending and verification.
   - `wallet`: money movement operations such as add money, withdraw, send money.
   - `transaction`: transaction history and ledger access.
   - `admin`: wallet blocking/unblocking and agent approval/suspension.
   - `notification`: persisted notification records and delivery support.
   - `ai`: isolated AI-facing endpoints/services, kept separate from the wallet core.

5. **Data and persistence layer**
   - MongoDB with Mongoose is the primary database layer.
   - The modules with `.model.ts` files define the persisted entities: user, wallet, transaction, and notification.
   - Business operations appear to read and mutate these models through services rather than directly from controllers.
   - This is the main persistence boundary for the system’s state.

6. **Money movement and transaction flow**
   - Wallet actions are central to the architecture and are handled in the `wallet` service.
   - Transactions are described as atomic: balance updates and transaction records are coordinated together.
   - The system tracks transaction type, amount, fee, commission, initiator, and status.
   - Status progression is part of the domain model: pending, completed, reversed.
   - Admin wallet blocking affects whether downstream money operations can proceed.

7. **Identity, roles, and authorization**
   - Authentication uses JWTs.
   - Role-based access control is enforced by `checkAuth` middleware.
   - Roles are explicitly part of the domain model: admin, user, agent.
   - Access boundaries are role-specific: users move money, agents perform cash-in/cash-out actions, admins supervise and control the system.

8. **OTP, password reset, and email delivery**
   - OTP flows are split into their own module and use Redis as a temporary store for short-lived codes.
   - Email delivery is handled via `sendEmail` utilities and EJS templates in `src/app/utils/templates`.
   - This creates a clear async boundary: request triggers OTP generation, Redis stores it, email is sent, then verification updates user state.

9. **Validation and error handling**
   - Request validation is layered in through `validateRequest` and Zod-based schemas in module-specific `*.validation.ts` files.
   - The app has centralized error normalization for common failure types: cast errors, duplicate key errors, validation errors, and Zod errors.
   - `globalErrorHandler` and `notFound` form the final HTTP error boundary.
   - `AppError` is the common application-level exception type.

10. **Shared utilities and cross-cutting concerns**
   - `catchAsync` standardizes async controller error propagation.
   - `sendResponse` centralizes response formatting.
   - `setCookie` and JWT helpers support session/token handling.
   - `seedAdmin` suggests bootstrap logic for provisioning a default admin account.
   - These utilities reduce duplication across modules and keep controllers thin.

11. **Realtime and notifications**
   - The presence of `socketManager` plus a notification module indicates a secondary event-delivery path beyond plain REST.
   - Notifications are modeled separately from transactions, which implies the system can persist events and optionally push them in realtime.
   - This is a distinct integration boundary from the core money and auth flows.

12. **Deployment shape**
   - `vercel.json` indicates the API is deployed in a serverless-friendly environment.
   - `dist/` is the production build output, so the runtime likely executes compiled JavaScript rather than TypeScript directly.
   - Environment configuration is centralized in `src/app/config/env.ts`, with `.env.example` documenting required variables.

Main entry points: [`src/app/routes/index.ts`](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/routes/index.ts) (Routes), [`src/app.ts`](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app.ts) (App), [`src/app/utils/sendResponse.ts`](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/sendResponse.ts) (Response), [`src/app/modules/wallet/wallet.route.ts`](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/wallet/wallet.route.ts) (Wallet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["Server<br/>entry<br/>[server.ts]"]
  node_app["App<br/>bootstrap<br/>[app.ts]"]
  node_routes["Routes<br/>composition<br/>[index.ts]"]
  node_socket(("Socket<br/>realtime<br/>[socketManager.ts]"))
end

subgraph group_crosscutting["Cross-cutting"]
  node_checkauth["Auth Guard<br/>middleware<br/>[checkAuth.ts]"]
  node_validate["Validate<br/>middleware<br/>[validateRequest.ts]"]
  node_errorhandler["Errors<br/>middleware"]
  node_env["Env<br/>config<br/>[env.ts]"]
  node_redis[("Redis<br/>config<br/>[redis.config.ts]")]
  node_jwt["JWT<br/>auth util<br/>[jwt.ts]"]
  node_sendemail["Email<br/>delivery util<br/>[sendEmail.ts]"]
  node_sendresponse["Response<br/>http util<br/>[sendResponse.ts]"]
  node_catchasync["Async Wrap<br/>http util<br/>[catchAsync.ts]"]
end

subgraph group_features["Feature modules"]
  node_auth["Auth<br/>feature module<br/>[auth.route.ts]"]
  node_otp["OTP<br/>feature module<br/>[otp.route.ts]"]
  node_wallet["Wallet<br/>feature module<br/>[wallet.route.ts]"]
  node_transaction["Txn<br/>feature module"]
  node_admin["Admin<br/>feature module<br/>[admin.route.ts]"]
  node_user["User<br/>feature module<br/>[user.route.ts]"]
  node_notification["Notify<br/>feature module"]
  node_ai["AI<br/>feature module<br/>[ai.route.ts]"]
end

subgraph group_data["Data layer"]
  node_usermodel[("User Model<br/>mongoose model<br/>[user.model.ts]")]
  node_walletmodel[("Wallet Model<br/>mongoose model<br/>[wallet.model.ts]")]
  node_txmodel[("Txn Model<br/>mongoose model")]
  node_notifmodel[("Notif Model<br/>mongoose model")]
end

node_server -->|"starts"| node_app
node_app -->|"mounts"| node_routes
node_app -->|"initializes"| node_socket
node_app -->|"uses"| node_checkauth
node_app -->|"uses"| node_validate
node_app -->|"terminates with"| node_errorhandler
node_routes -->|"wires"| node_auth
node_routes -->|"wires"| node_otp
node_routes -->|"wires"| node_wallet
node_routes -->|"wires"| node_transaction
node_routes -->|"wires"| node_admin
node_routes -->|"wires"| node_user
node_routes -->|"wires"| node_notification
node_routes -->|"wires"| node_ai
node_auth -->|"issues"| node_jwt
node_auth -->|"responds"| node_sendresponse
node_auth -->|"wraps"| node_catchasync
node_otp -->|"stores"| node_redis
node_otp -->|"delivers"| node_sendemail
node_otp -->|"validates"| node_validate
node_wallet -->|"mutates"| node_walletmodel
node_wallet -->|"records"| node_txmodel
node_wallet -->|"protects"| node_checkauth
node_transaction -->|"reads"| node_txmodel
node_admin -->|"controls"| node_walletmodel
node_admin -->|"governs"| node_usermodel
node_user -->|"creates"| node_usermodel
node_notification -->|"persists"| node_notifmodel
node_notification -->|"pushes"| node_socket
node_wallet -->|"responds"| node_sendresponse
node_transaction -->|"responds"| node_sendresponse
node_admin -->|"responds"| node_sendresponse
node_user -->|"responds"| node_sendresponse
node_notification -->|"responds"| node_sendresponse

click node_server "https://github.com/adir-jscode/walletxpress-api/blob/main/src/server.ts"
click node_app "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app.ts"
click node_routes "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/routes/index.ts"
click node_socket "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/socket/socketManager.ts"
click node_checkauth "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/middlewares/checkAuth.ts"
click node_validate "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/middlewares/validateRequest.ts"
click node_errorhandler "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/middlewares/globalErrorHandler.ts"
click node_env "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/config/env.ts"
click node_redis "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/config/redis.config.ts"
click node_jwt "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/jwt.ts"
click node_sendemail "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/sendEmail.ts"
click node_sendresponse "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/sendResponse.ts"
click node_catchasync "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/catchAsync.ts"
click node_auth "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/auth/auth.route.ts"
click node_otp "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/Otp/otp.route.ts"
click node_wallet "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/wallet/wallet.route.ts"
click node_transaction "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/transaction/transaction.route.ts"
click node_admin "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/admin/admin.route.ts"
click node_user "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/user/user.route.ts"
click node_notification "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/notification/notification.route.ts"
click node_ai "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/ai/ai.route.ts"
click node_usermodel "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/user/user.model.ts"
click node_walletmodel "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/wallet/wallet.model.ts"
click node_txmodel "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/transaction/transaction.model.ts"
click node_notifmodel "https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/notification/notification.model.ts"

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_server,node_app,node_routes,node_socket toneBlue
class node_checkauth,node_validate,node_errorhandler,node_env,node_redis,node_jwt,node_sendemail,node_sendresponse,node_catchasync toneAmber
class node_auth,node_otp,node_wallet,node_transaction,node_admin,node_user,node_notification,node_ai toneMint
class node_usermodel,node_walletmodel,node_txmodel,node_notifmodel toneRose
```

## Components

### Runtime

Process entry, app bootstrap, routes, and realtime integration.

- [Server](https://github.com/adir-jscode/walletxpress-api/blob/main/src/server.ts): entry · Starts the API process. · `src/server.ts`
- [App](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app.ts): bootstrap · Builds the Express app and wires middleware. · `src/app.ts`
- [Routes](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/routes/index.ts): composition · Mounts feature routers under the API. · `src/app/routes/index.ts`
- [Socket](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/socket/socketManager.ts): realtime · Realtime event integration. · `src/app/socket/socketManager.ts`

### Cross-cutting

Middleware, helpers, configuration, and shared infrastructure.

- [Auth Guard](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/middlewares/checkAuth.ts): middleware · JWT and role-based access control. · `src/app/middlewares/checkAuth.ts`
- [Validate](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/middlewares/validateRequest.ts): middleware · Request schema validation boundary. · `src/app/middlewares/validateRequest.ts`
- [Errors](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/middlewares/globalErrorHandler.ts): middleware · Final HTTP error normalization and handling. · `src/app/middlewares/globalErrorHandler.ts`
- [Env](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/config/env.ts): config · Central environment configuration. · `src/app/config/env.ts`
- [Redis](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/config/redis.config.ts): config · Short-lived OTP and cache store configuration. · `src/app/config/redis.config.ts`
- [JWT](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/jwt.ts): auth util · Token creation and verification helpers. · `src/app/utils/jwt.ts`
- [Email](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/sendEmail.ts): delivery util · Email delivery and template rendering. · `src/app/utils/sendEmail.ts`
- [Response](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/sendResponse.ts): http util · Standardized API response formatting. · `src/app/utils/sendResponse.ts`
- [Async Wrap](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/utils/catchAsync.ts): http util · Async controller error propagation helper. · `src/app/utils/catchAsync.ts`

### Feature modules

Domain modules exposed through routes and services.

- [Auth](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/auth/auth.route.ts): feature module · Login, refresh, logout, and password flows. · `src/app/modules/auth/auth.route.ts`
- [OTP](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/Otp/otp.route.ts): feature module · Email OTP generation and verification. · `src/app/modules/Otp/otp.route.ts`
- [Wallet](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/wallet/wallet.route.ts): feature module · Cash-in, cash-out, send-money, and balance operations. · `src/app/modules/wallet/wallet.route.ts`
- [Txn](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/transaction/transaction.route.ts): feature module · Ledger and transaction history access. · `src/app/modules/transaction/transaction.route.ts`
- [Admin](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/admin/admin.route.ts): feature module · Wallet controls and agent supervision. · `src/app/modules/admin/admin.route.ts`
- [User](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/user/user.route.ts): feature module · Registration and user/agent management. · `src/app/modules/user/user.route.ts`
- [Notify](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/notification/notification.route.ts): feature module · Persisted notifications and delivery support. · `src/app/modules/notification/notification.route.ts`
- [AI](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/ai/ai.route.ts): feature module · Isolated AI-facing endpoints and services. · `src/app/modules/ai/ai.route.ts`

### Data layer

Primary persisted entities managed through Mongoose models.

- [User Model](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/user/user.model.ts): mongoose model · Persistent user and role state. · `src/app/modules/user/user.model.ts`
- [Wallet Model](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/wallet/wallet.model.ts): mongoose model · Account balance and wallet state. · `src/app/modules/wallet/wallet.model.ts`
- [Txn Model](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/transaction/transaction.model.ts): mongoose model · Atomic transaction records and status. · `src/app/modules/transaction/transaction.model.ts`
- [Notif Model](https://github.com/adir-jscode/walletxpress-api/blob/main/src/app/modules/notification/notification.model.ts): mongoose model · Stored notification records. · `src/app/modules/notification/notification.model.ts`

## Connections

- Server → App: starts · Bootstraps the API process.
- App → Routes: mounts · Composes and mounts the API routers.
- App → Socket: initializes · Attaches realtime event handling.
- App → Auth Guard: uses · Applies auth and role controls.
- App → Validate: uses · Applies request validation.
- App → Errors: terminates with · Centralized error boundary.
- Routes → Auth: wires · Mounts auth endpoints.
- Routes → OTP: wires · Mounts OTP endpoints.
- Routes → Wallet: wires · Mounts wallet endpoints.
- Routes → Txn: wires · Mounts transaction endpoints.
- Routes → Admin: wires · Mounts admin endpoints.
- Routes → User: wires · Mounts user endpoints.
- Routes → Notify: wires · Mounts notification endpoints.
- Routes → AI: wires · Mounts AI endpoints.
- Auth → JWT: issues · Creates and verifies JWT sessions.
- Auth → Response: responds · Uses shared response formatting.
- Auth → Async Wrap: wraps · Async controller safety.
- OTP → Redis: stores · Keeps short-lived OTP codes.
- OTP → Email: delivers · Sends OTP and reset emails.
- OTP → Validate: validates · Schema validation for OTP requests.
- Wallet → Wallet Model: mutates · Updates balances and wallet state.
- Wallet → Txn Model: records · Persists transactional outcomes.
- Wallet → Auth Guard: protects · Role-gated money movement.
- Txn → Txn Model: reads · Serves ledger and history.
- Admin → Wallet Model: controls · Blocks and unblocks wallets.
- Admin → User Model: governs · Approves and suspends agents/users.
- User → User Model: creates · Registers and manages user state.
- Notify → Notif Model: persists · Stores notification records.
- Notify → Socket: pushes · Optional realtime delivery path.
- Wallet → Response: responds · Uses shared response formatting.
- Txn → Response: responds · Uses shared response formatting.
- Admin → Response: responds · Uses shared response formatting.
- User → Response: responds · Uses shared response formatting.
- Notify → Response: responds · Uses shared response formatting.