# brparthib/digital-wallet-system-server architecture

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

- Interactive diagram: https://gitdiagram.com/brparthib/digital-wallet-system-server
- Repository: https://github.com/brparthib/digital-wallet-system-server

## Overview

1. **System shape**
   This is a TypeScript backend API for a digital wallet platform. The source of truth is `src/`, and `dist/` is the compiled JavaScript output. The app is organized as a modular Express + Mongoose service rather than a monolith with one large controller layer.

2. **Runtime and entrypoints**
   The main startup path is `src/server.ts`, which boots the HTTP server, and `src/app.ts`, which assembles the Express application. The runtime is Node.js, with environment-driven configuration loaded from `src/app/configs/envCon.ts`.

3. **Request pipeline**
   Incoming requests go through common middleware first: auth checks, request validation, 404 handling, and a global error handler. From there, routing dispatches to feature modules, each following the same flow: route → controller → service → model/database.

4. **Feature modules**
   The app is split into five core domains:
   - `auth`: login, refresh token, logout, password reset
   - `user`: user lifecycle and status management
   - `wallet`: wallet creation and wallet state changes
   - `transaction`: money movement and transaction history
   - `feedback`: feedback submission and retrieval
   There is also a `stats` module, likely for admin/reporting views built from transactional data.

5. **Domain/data boundaries**
   Each module keeps its own controller, service, route, and in most cases model, interface, and validation files. This indicates a clear separation between HTTP concerns, business rules, and persistence. Transaction and wallet logic are distinct, which matters because wallet balance updates and transaction recording are likely coordinated but not merged into one subsystem.

6. **Persistence layer**
   MongoDB is the primary datastore via Mongoose models. Wallets, users, transactions, and feedback each have their own model definitions. The README indicates that wallets are auto-created for users and that all financial actions are persisted in the transaction model, making transaction history a first-class data boundary.

7. **Authorization and roles**
   Access control is enforced with a `checkAuth` middleware and role-based behavior described in the README: admin, agent, and user. Admin can manage agent/user status and wallet blocking; agents can perform cash-in/cash-out; users can send money and view history. Auth uses JWT access and refresh tokens stored in cookies.

8. **Business logic focus**
   The core financial flows are:
   - **Cash-in / add money** by agent
   - **Cash-out / withdraw** by agent
   - **Send money** user-to-user
   These flows likely update wallet balances, create transaction records, and apply fee/commission rules. The README specifically notes automatic fee credit to the admin wallet and commission handling for agents on cash-out.

9. **Validation, errors, and responses**
   Request schemas are validated through `validateRequest`, with module-level validation files using Zod. Application errors are normalized through `AppError` / `handleError`, and async controller code is wrapped with `catchAsync`. Responses are standardized via `sendResponse`, which suggests a consistent API shape across modules.

10. **Utility and support layer**
   Shared utilities handle reusable infrastructure concerns: JWT helpers, cookie setting, query building, transaction ID generation, country-code normalization, and seeding scripts. The seed helpers indicate the app can bootstrap an admin and dummy users/agents, which is important for local setup and demo data.

11. **Deployment/config surface**
   Configuration is driven by environment variables for MongoDB, JWT secrets, password hashing, and wallet policy thresholds like minimum balance and percentage/charge limits. The presence of `vercel.json` suggests deployment packaging is already considered, but the architecture is still fundamentally an API server backed by MongoDB.

12. **How to diagram it**
   A good architecture diagram should show:
   client requests → Express app → shared middleware layer → module routes/controllers → business services → Mongoose models → MongoDB, with cross-cutting paths for auth, validation, and centralized error handling. The most important domain-specific links are between wallet operations and transaction recording, plus admin-controlled status/limits that influence those flows.

Main entry points: [`src/app/routes/index.ts`](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/routes/index.ts) (API routes), [`src/app.ts`](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app.ts) (Express app), [`src/app/modules/wallet/wallet.service.ts`](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/wallet/wallet.service.ts) (Wallet svc), [`src/app/modules/transaction/transaction.service.ts`](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/transaction/transaction.service.ts) (Txn svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_client(("Client<br/>API consumer"))
  node_server["Server<br/>startup<br/>[server.ts]"]
  node_app["Express app<br/>app assembly<br/>[app.ts]"]
end

subgraph group_crosscutting["Cross-cutting"]
  node_env["Env config<br/>[envCon.ts]"]
  node_authmw["Auth check<br/>middleware<br/>[checkAuth.ts]"]
  node_validate["Validate req<br/>middleware<br/>[validateRequest.ts]"]
  node_errors["Error stack<br/>middleware+errors<br/>[AppError.ts]"]
  node_routes["API routes<br/>router<br/>[index.ts]"]
end

subgraph group_modules["Feature modules"]
  node_authmod["Auth<br/>[auth.route.ts]"]
  node_usermod["User<br/>[user.route.ts]"]
  node_walletmod["Wallet<br/>[wallet.route.ts]"]
  node_txmod["Transaction"]
  node_feedbackmod["Feedback<br/>[feedback.route.ts]"]
  node_statsmod["Stats<br/>[stats.route.ts]"]
  node_authsvc["Auth svc<br/>[auth.service.ts]"]
  node_walletsvc["Wallet svc<br/>[wallet.service.ts]"]
  node_txsvc["Txn svc"]
end

subgraph group_data["Persistence"]
  node_models[("Mongo models<br/>persistence<br/>[user.model.ts]")]
end

subgraph group_support["Support"]
  node_utils["Shared utils<br/>helpers<br/>[jwt.ts]"]
end

node_client -->|"HTTP"| node_server
node_server -->|"boot"| node_app
node_app -->|"config"| node_env
node_app -->|"middleware"| node_authmw
node_app -->|"middleware"| node_validate
node_app -->|"mount"| node_routes
node_app -->|"handle"| node_errors
node_routes -->|"auth"| node_authmod
node_routes -->|"user"| node_usermod
node_routes -->|"wallet"| node_walletmod
node_routes -->|"transaction"| node_txmod
node_routes -->|"feedback"| node_feedbackmod
node_routes -->|"stats"| node_statsmod
node_authmod -->|"service"| node_authsvc
node_walletmod -->|"service"| node_walletsvc
node_txmod -->|"service"| node_txsvc
node_authsvc -->|"read/write"| node_models
node_walletsvc -->|"read/write"| node_models
node_txsvc -->|"write"| node_models
node_walletsvc -.->|"record txn"| node_txsvc
node_authsvc -->|"helpers"| node_utils
node_walletsvc -->|"helpers"| node_utils
node_txsvc -->|"helpers"| node_utils
node_validate -.->|"raise"| node_errors
node_authmw -.->|"protect"| node_authmod

click node_server "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/server.ts"
click node_app "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app.ts"
click node_env "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/configs/envCon.ts"
click node_authmw "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/middlewares/checkAuth.ts"
click node_validate "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/middlewares/validateRequest.ts"
click node_errors "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/errorHelpers/AppError.ts"
click node_routes "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/routes/index.ts"
click node_authmod "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/auth/auth.route.ts"
click node_usermod "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/user/user.route.ts"
click node_walletmod "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/wallet/wallet.route.ts"
click node_txmod "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/transaction/transaction.route.ts"
click node_feedbackmod "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/feedback/feedback.route.ts"
click node_statsmod "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/stats/stats.route.ts"
click node_authsvc "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/auth/auth.service.ts"
click node_walletsvc "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/wallet/wallet.service.ts"
click node_txsvc "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/transaction/transaction.service.ts"
click node_models "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/user/user.model.ts"
click node_utils "https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/utils/jwt.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_client,node_server,node_app toneBlue
class node_env,node_authmw,node_validate,node_errors,node_routes toneAmber
class node_authmod,node_usermod,node_walletmod,node_txmod,node_feedbackmod,node_statsmod,node_authsvc,node_walletsvc,node_txsvc toneMint
class node_models toneRose
class node_utils toneIndigo
```

## Components

### Runtime

Process entrypoints and startup

- **Client**: API consumer · External HTTP caller
- [Server](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/server.ts): startup · Bootstraps the HTTP listener · `src/server.ts`
- [Express app](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app.ts): app assembly · Wires middleware and routes · `src/app.ts`

### Cross-cutting

Shared middleware, errors, and config

- [Env config](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/configs/envCon.ts): config · Environment-driven settings · `src/app/configs/envCon.ts`
- [Auth check](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/middlewares/checkAuth.ts): middleware · JWT and role gatekeeping · `src/app/middlewares/checkAuth.ts`
- [Validate req](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/middlewares/validateRequest.ts): middleware · Zod request validation · `src/app/middlewares/validateRequest.ts`
- [Error stack](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/errorHelpers/AppError.ts): middleware+errors · AppError, handler, 404 and global error flow · `src/app/errorHelpers/AppError.ts`
- [API routes](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/routes/index.ts): router · Top-level route composition · `src/app/routes/index.ts`

### Feature modules

Domain-specific API areas

- [Auth](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/auth/auth.route.ts): module · Login, refresh, logout, reset · `src/app/modules/auth/auth.route.ts`
- [User](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/user/user.route.ts): module · User lifecycle and status · `src/app/modules/user/user.route.ts`
- [Wallet](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/wallet/wallet.route.ts): module · Wallet creation and state changes · `src/app/modules/wallet/wallet.route.ts`
- [Transaction](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/transaction/transaction.route.ts): module · Money movement and history · `src/app/modules/transaction/transaction.route.ts`
- [Feedback](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/feedback/feedback.route.ts): module · Submit and retrieve feedback · `src/app/modules/feedback/feedback.route.ts`
- [Stats](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/stats/stats.route.ts): module · Reporting and admin summaries · `src/app/modules/stats/stats.route.ts`
- [Auth svc](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/auth/auth.service.ts): service · Token and session logic · `src/app/modules/auth/auth.service.ts`
- [Wallet svc](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/wallet/wallet.service.ts): service · Balance and wallet state rules · `src/app/modules/wallet/wallet.service.ts`
- [Txn svc](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/transaction/transaction.service.ts): service · Transfer, cash-in, cash-out flows · `src/app/modules/transaction/transaction.service.ts`

### Persistence

Database-backed models and storage

- [Mongo models](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/modules/user/user.model.ts): persistence · User, wallet, transaction, feedback documents · `src/app/modules/user/user.model.ts`

### Support

Reusable utilities and bootstrap helpers

- [Shared utils](https://github.com/brparthib/digital-wallet-system-server/blob/development/src/app/utils/jwt.ts): helpers · JWT, cookies, responses, IDs, seeding · `src/app/utils/jwt.ts`

## Connections

- Client → Server: HTTP · Requests enter the Node process
- Server → Express app: boot · Server initializes the Express app
- Express app → Env config: config · Loads runtime settings
- Express app → Auth check: middleware · Applies auth checks to protected paths
- Express app → Validate req: middleware · Validates incoming payloads
- Express app → API routes: mount · Registers API routes
- Express app → Error stack: handle · Adds 404 and global error handling
- API routes → Auth: auth · Dispatches to auth endpoints
- API routes → User: user · Dispatches to user endpoints
- API routes → Wallet: wallet · Dispatches to wallet endpoints
- API routes → Transaction: transaction · Dispatches to transaction endpoints
- API routes → Feedback: feedback · Dispatches to feedback endpoints
- API routes → Stats: stats · Dispatches to reporting endpoints
- Auth → Auth svc: service · Auth controllers delegate business logic
- Wallet → Wallet svc: service · Wallet controllers delegate business logic
- Transaction → Txn svc: service · Transaction controllers delegate business logic
- Auth svc → Mongo models: read/write · Authenticates users and persists session-related state
- Wallet svc → Mongo models: read/write · Updates wallet documents
- Txn svc → Mongo models: write · Records financial activity in MongoDB
- Wallet svc → Txn svc: record txn · Wallet changes are mirrored in transaction history
- Auth svc → Shared utils: helpers · Uses JWT and cookie helpers
- Wallet svc → Shared utils: helpers · Uses shared response and ID utilities
- Txn svc → Shared utils: helpers · Uses transaction ID and response helpers
- Validate req → Error stack: raise · Validation failures flow into centralized errors
- Auth check → Auth: protect · Secures admin, agent, and user actions