How yahia101imad/express-backend-starter works
1. Overall shape
- This is a modular Node.js/Express API backend centered around two business modules: auth and user.
- The code is organized by responsibility: application bootstrap, shared infrastructure, cross-cutting middleware, feature modules, and seed scripts.
2. Bootstrap and runtime entrypoints
- src/server.js is the process entrypoint that likely starts the HTTP server.
- src/app.js is the Express application composition layer, where middleware, routes, and docs are wired together before the server listens.
3. Routing boundary
- src/routes/index.js appears to be the top-level route aggregator.
- Feature routes are split by module, mainly src/modules/auth/auth.routes.js and src/modules/user/user.routes.js, which keeps endpoint ownership localized to each feature.
4. Auth module as the main security subsystem
- src/modules/auth/ contains the full authentication lifecycle:
- login/register flows in auth.controller.js and auth.service.js
- session persistence in session.model.js
- password reset tokens in password-reset-token.model.js
- email verification tokens in email-verification-token.model.js
- This module is the primary source of identity-related state changes in the system.
5. JWT and token flow
- src/common/auth/ contains token utilities for generating and validating access/refresh tokens.
- The readme indicates the system uses short-lived access tokens plus refresh tokens, so the auth flow likely issues tokens on login, verifies them in middleware, and uses stored sessions/tokens for logout and refresh behavior.
6. Authorization and RBAC
- src/common/constants/roles.js, permissions.js, and rolePermissions.js define the authorization model.
- src/middlewares/permission.middleware.js enforces role/permission checks after authentication, making authorization a separate layer from token verification.
7. User module as the domain data subsystem
- src/modules/user/ owns user CRUD and user-facing business logic through user.controller.js, user.service.js, and user.model.js.
- This module likely consumes the auth context for protected endpoints and is the main persistent entity outside of sessions and token records.
8. Persistence layer
- MongoDB + Mongoose is the persistence boundary, configured in src/config/db.js.
- Each module owns its own models, which suggests a feature-aligned data model rather than a single centralized repository layer.
9. Cross-cutting middleware pipeline
- src/middlewares/ holds the request pipeline concerns:
- authentication
- permission checks
- validation
- rate limiting
- centralized error handling
- The request path is therefore: route → validation/authz middleware → controller/service → model/database → response or error handler.
10. Validation and response shaping
- src/modules/auth/validators/auth.schema.js defines request schemas for auth endpoints.
- src/common/utils/sendResponse.js standardizes successful API responses, while src/common/errors/appError.js provides a structured app-level error type for the error middleware to interpret.
11. Configuration and infrastructure concerns
- src/config/env.js, security.js, logger.js, and Swagger config files centralize environment parsing, security settings, logging, and API documentation setup.
- These files form the app’s infrastructure boundary and are consumed by bootstrap and middleware layers rather than business modules.
12. API documentation
- src/config/swagger.js and src/config/swagger.components.js indicate Swagger/OpenAPI docs are generated from code configuration and exposed as part of the app.
- This is a supporting subsystem, not part of request execution, but it mirrors the API surface for consumers.
13. Background/admin setup
- src/seed/admin.seed.js is a bootstrap data script for creating an initial admin account.
- This suggests the system expects at least one privileged seed identity for development or first-run setup.
14. Shared utilities
- src/utils/asyncHandler.js likely wraps async controllers to forward errors cleanly to the error middleware.
- src/utils/pagination.js supports list endpoints, aligning with the readme’s mention of pagination/filtering work.
15. External dependencies that materially shape the architecture
- The core external boundary is MongoDB/Mongoose for persistence.
- JWT is the primary security mechanism for stateless request authentication.
- Swagger/OpenAPI is used for API contract documentation.
- The architecture is otherwise a conventional Express service with explicit module boundaries and shared cross-cutting infrastructure.
Main entry points: auth.service.js Auth svc · auth.routes.js Auth routes · app.js App · user.routes.js User routes
Components 34
Runtime
Process bootstrap and Express application wiring.
Infrastructure
Configuration, logging, persistence, and API documentation.
- Database · MongoDB connection and persistence setup.
src/config/db.js - Env · Parses runtime environment and application settings.
src/config/env.js - Security · Central security-related configuration.
src/config/security.js - Logger · Application logging configuration.
src/config/logger.js - Swagger · Builds API documentation configuration.
src/config/swagger.js - Docs schema · Shared OpenAPI component definitions.
src/config/swagger.components.js
Cross-cutting
Shared middleware, auth helpers, errors, and utilities.
- Auth mw · Verifies access tokens and attaches request identity.
src/middlewares/auth.middleware.js - Permission mw · Enforces role and permission checks.
src/middlewares/permission.middleware.js - Validate mw · Runs request schema validation before handlers.
src/middlewares/validate.middleware.js - Error mw · Normalizes application errors into responses.
src/middlewares/error.middleware.js - Rate limit · Limits request throughput to protect endpoints.
src/middlewares/rateLimit.middleware.js - Token utils · Generates and verifies access and refresh tokens.
src/common/auth - Roles · Role, permission, and role-to-permission definitions.
src/common/constants - App error · Structured error object consumed by error handling.
src/common/errors/appError.js - Response · Standard response formatting helper.
src/common/utils/sendResponse.js - Async handler · Wraps async route handlers for error forwarding.
src/utils/asyncHandler.js - Pagination · Shared list pagination helper.
src/utils/pagination.js
Feature modules
Domain modules for auth and user management.
- Auth · Authentication, tokens, sessions, and account recovery.
src/modules/auth - Auth ctl · Handles login, registration, verification, and reset flows.
src/modules/auth/auth.controller.js - Auth svc · Implements authentication business logic.
src/modules/auth/auth.service.js - Auth routes · Feature routes for authentication endpoints.
src/modules/auth/auth.routes.js - Session · Stores active session state and token lifecycle data.
src/modules/auth/session.model.js - Reset token · Persists password reset tokens.
src/modules/auth/password-reset-token.model.js - Verify token · Persists email verification tokens.
src/modules/auth/email-verification-token.model.js - Auth schema · Request validation rules for auth endpoints.
src/modules/auth/validators/auth.schema.js - User · User domain state and protected user operations.
src/modules/user - User ctl · Handles user-facing CRUD and profile actions.
src/modules/user/user.controller.js - User svc · Implements user business logic.
src/modules/user/user.service.js - User routes · Feature routes for user endpoints.
src/modules/user/user.routes.js - User model · Primary user persistence model.
src/modules/user/user.model.js
Support
Seed and background setup scripts.
- Admin seed · Creates an initial privileged admin account.
src/seed/admin.seed.js
Connections 48
- Server → App: boots · Process entrypoint starts the Express application.
- App → Routes: mounts · Application wiring delegates endpoint registration to the route aggregator.
- App → Swagger: documents · Exposes API documentation alongside the app.
- Swagger → Docs schema: uses · Swagger config references shared component definitions.
- App → Error mw: uses · Central error handling is installed at the application boundary.
- App → Rate limit: uses · Request throttling is applied as cross-cutting middleware.
- App → Security: uses · Security settings shape request handling and docs.
- App → Logger: uses · Application bootstrapping initializes logging.
- Routes → Auth routes: mounts · Top-level router mounts auth endpoints.
- Routes → User routes: mounts · Top-level router mounts user endpoints.
- Auth routes → Validate mw: validates · Auth routes run request schema validation.
- Auth routes → Auth mw: protects · Protected auth flows use authentication middleware where needed.
- Auth routes → Permission mw: authorizes · Role and permission checks gate privileged auth actions.
- User routes → Auth mw: protects · User endpoints are guarded by token authentication.
- User routes → Permission mw: authorizes · User endpoints can require permission checks.
- User routes → Pagination: lists · User listing endpoints can use shared pagination behavior.
- Auth ctl → Auth svc: delegates · Controller forwards business work to the auth service.
- Auth svc → Session: persists · Auth flow stores and updates session state.
- Auth svc → Reset token: persists · Password reset tokens are created and consumed here.
- Auth svc → Verify token: persists · Email verification tokens are managed here.
- Auth svc → Token utils: signs · Token utilities issue and validate JWTs.
- Auth svc → Response: formats · Successful responses use the shared response helper.
- Auth svc → App error: raises · Business failures are surfaced as structured app errors.
- Auth routes → Auth ctl: dispatches · Auth routes hand off to the controller layer.
- Auth routes → Auth schema: validates · Auth endpoint inputs are checked against schemas.
- Auth routes → Async handler: wraps · Async handler utility helps route execution propagate errors.
- User ctl → User svc: delegates · User controller forwards domain work to the service.
- User svc → User model: persists · User data is read from and written to the database.
- User svc → Response: formats · User APIs standardize success responses.
- User svc → App error: raises · User business errors use the shared error type.
- User routes → User ctl: dispatches · User routes route requests to the controller.
- User routes → Async handler: wraps · Async handler utility shields route handlers from unhandled rejections.
- Auth → Auth ctl: contains · Auth module is implemented through its controller.
- Auth → Auth svc: contains · Auth module is implemented through its service.
- Auth → Auth routes: contains · Auth module exposes its own router.
- User → User ctl: contains · User module is implemented through its controller.
- User → User svc: contains · User module is implemented through its service.
- User → User routes: contains · User module exposes its own router.
- Database → Session: backs · MongoDB/Mongoose supports session persistence.
- Database → Reset token: backs · MongoDB/Mongoose supports reset token storage.
- Database → Verify token: backs · MongoDB/Mongoose supports verification token storage.
- Database → User model: backs · MongoDB/Mongoose supports user persistence.
- Env → Database: configures · Environment settings drive database connection setup.
- Roles → Permission mw: drives · Authorization middleware consumes role and permission constants.
- Roles → Auth svc: drives · Auth logic uses the role model when creating accounts and sessions.
- Admin seed → User model: creates · Seed script creates an initial admin user.
- Auth mw → Token utils: verifies · Authentication middleware validates JWTs.
- Auth mw → App error: raises · Invalid or missing credentials become structured errors.