brparthib/digital-wallet-system-server

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.