adir-jscode/walletxpress-api

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.