# hagopj13/node-express-boilerplate architecture

> Architecture diagram of the GitHub repository hagopj13/node-express-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hagopj13/node-express-boilerplate
- Repository: https://github.com/hagopj13/node-express-boilerplate

## Overview

##### Main Components
- Client/Consumer: Although not part of the repository, external clients (e.g., browser-based apps, mobile apps, or other services) will call the RESTful endpoints.
- API Gateway (Express Server): The heart of the system where the Express application is set up (see src/app.js and src/index.js). This handles incoming HTTP requests.
- Routes Layer: Located in src/routes (with versioned routes under v1) that maps HTTP endpoints to controller functions.
- Controllers: In src/controllers, these components process incoming requests, call the relevant business logic, and send responses. For example, auth.controller.js and user.controller.js.
- Services Layer: Found in src/services, which contains the core business logic (e.g., authentication, email handling, token management, and user services). These abstract complex operations away from the controllers.
- Models and Data Layer: Inside src/models, Mongoose models (e.g., user.model.js and token.model.js) define the data schema for MongoDB. This includes custom plugins (in src/models/plugins) like paginate and toJSON.
- Middleware: In src/middlewares, which covers authentication, error handling, rate-limiting, input validation, etc. These components intercept requests and responses to augment functionality.
- Configuration and Utilities: Found in src/config and src/utils. You have configuration settings such as logging, passport, tokens, and environment variables. Utilities (ApiError, catchAsync, pick) simplify common code patterns.
- Documentation: The API documentation resources in src/docs that, when the server is running, provide a Swagger-based UI for inspecting endpoints.
- Testing: Tests are organized under tests/ (both integration and unit tests) ensuring system quality and behavior.

##### Interactions and Relationships
- Externally, a client makes HTTP requests to the Express server.
- The Express server’s routing layer directs the request to the appropriate controller based on the URL path (e.g., /v1/auth/login or /v1/users).
- Controllers process the input and delegate work to service components. In the process, they make use of validation middleware (e.g., using Joi schemas) and check for authentication/authorization via auth middleware.
- Business logic implemented in the services may interact with the database via Mongoose models. Here, custom plugins (like toJSON and paginate) enhance the data layer.
- Logging middleware (using morgan and winston) and error handling middleware capture runtime information and errors.
- For operations that need asynchronous support (for example, sending emails or token generation), the services interact with external systems or internal utilities.
- Finally, a response is sent back to the client, optionally including API documentation endpoints for exploration.

##### Architectural Patterns & Design Principles
- Layered Architecture: Clear separation of concerns is maintained through controllers (presentation layer), services (business logic layer), and models (data persistence layer).
- Middleware-driven Request Processing: Express middlewares handle authentication, error-handling, rate limiting, and data validation.
- Modular and Pluggable: The use of plugins for Mongoose models and separate modules for validation, logging, and configuration encapsulate functionality.
- Container & Process Management: Dockerfiles and Docker Compose files show readiness for containerized deployment, while PM2 (ecosystem.config.json) handles process management in production.
- Comprehensive Testing: The separation of unit and integration tests reinforces a test-driven approach.

##### Relevant Technologies and Frameworks
- Technologies: Node.js, Express, MongoDB, Mongoose.
- Authentication: JWT and Passport.
- Validation: Joi.
- Logging: Winston and Morgan.
- Process Management: PM2.
- API Documentation: Swagger (swagger-jsdoc and swagger-ui-express).
- Testing: Jest.
- Containerization: Docker and Docker Compose.
- Code Quality: ESLint, Prettier, and Git hooks via Husky.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "External Client"
        C["Client"]:::client
    end

    subgraph "API Gateway (Express)"
        A1["Express App Setup"]:::gateway
        A2["Server Entry"]:::gateway
    end

    subgraph "Middlewares"
        MW1["Auth Middleware"]:::middleware
        MW2["Error Middleware"]:::middleware
        MW3["RateLimiter Middleware"]:::middleware
        MW4["Validate Middleware"]:::middleware
    end

    subgraph "Routes Layer"
        R1["Auth Route"]:::routes
        R2["Docs Route"]:::routes
        R3["User Route"]:::routes
        R4["Index Route"]:::routes
    end

    subgraph "Controllers"
        CT1["Auth Controller"]:::controllers
        CT2["User Controller"]:::controllers
        CT3["Controller Index"]:::controllers
    end

    subgraph "Services Layer"
        S1["Auth Service"]:::services
        S2["Email Service"]:::services
        S3["Token Service"]:::services
        S4["User Service"]:::services
        S5["Service Index"]:::services
    end

    subgraph "Models & Data Layer"
        M1["User Model"]:::models
        M2["Token Model"]:::models
        M3["Model Index"]:::models
        subgraph "Plugins"
            P1["Paginate Plugin"]:::models
            P2["toJSON Plugin"]:::models
            P3["Plugins Index"]:::models
        end
    end

    subgraph "Configuration & Utilities"
        CFG1["Config"]:::config
        CFG2["Logger"]:::config
        CFG3["Morgan"]:::config
        CFG4["Passport"]:::config
        CFG5["Roles"]:::config
        CFG6["Tokens"]:::config
        U1["APIError"]:::config
        U2["catchAsync"]:::config
        U3["pick"]:::config
    end

    subgraph "Documentation"
        D1["Swagger Definition"]:::doc
        D2["Components YAML"]:::doc
    end

    subgraph "Validations"
        V1["Auth Validation"]:::validation
        V2["Custom Validation"]:::validation
        V3["User Validation"]:::validation
        V4["Validations Index"]:::validation
    end

    subgraph "Testing"
        T1["Integration Auth Test"]:::test
        T2["Integration Docs Test"]:::test
        T3["Integration User Test"]:::test
        T4["Unit Error Middleware Test"]:::test
        T5["Other Tests"]:::test
    end

    C --> A1
    A1 --> A2

    A1 --> MW1
    A1 --> MW2
    A1 --> MW3
    A1 --> MW4

    A1 --> R1
    A1 --> R2
    A1 --> R3
    A1 --> R4

    MW4 --> R1
    MW4 --> R2
    MW4 --> R3
    MW4 --> R4

    R1 --> CT1
    R3 --> CT2
    R4 --> CT3
    R2 --> D1

    CT1 --> S1
    CT1 --> S2
    CT2 --> S4
    CT3 --> S5

    S1 --> S3
    S3 --> M2
    S4 --> M1
    S5 --> M3

    R1 --> V1
    R2 --> V2
    R3 --> V3
    R4 --> V4

    A1 --> CFG1
    CFG1 --> CFG2
    CFG1 --> CFG3
    CFG1 --> CFG4
    CFG1 --> CFG5
    CFG1 --> CFG6
    CFG1 --> U1
    CFG1 --> U2
    CFG1 --> U3

    M1 --> P1
    M1 --> P2
    P1 --> P3

    D1 --> D2

    T1 --- A1
    T2 --- A1
    T3 --- A1
    T4 --- A1
    T5 --- A1

classDef client fill:#FFD700,stroke:#333,stroke-width:2px;
classDef gateway fill:#87CEEB,stroke:#333,stroke-width:2px;
classDef routes fill:#ADD8E6,stroke:#333,stroke-width:2px;
classDef controllers fill:#98FB98,stroke:#333,stroke-width:2px;
classDef services fill:#FFB6C1,stroke:#333,stroke-width:2px;
classDef models fill:#FFA500,stroke:#333,stroke-width:2px;
classDef middleware fill:#DDA0DD,stroke:#333,stroke-width:2px;
classDef config fill:#F5DEB3,stroke:#333,stroke-width:2px;
classDef doc fill:#E6E6FA,stroke:#333,stroke-width:2px;
classDef validation fill:#E0FFFF,stroke:#333,stroke-width:2px;
classDef test fill:#D3D3D3,stroke:#333,stroke-width:2px;

click A1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/app.js"
click A2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/index.js"
click R1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/routes/v1/auth.route.js"
click R2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/routes/v1/docs.route.js"
click R3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/routes/v1/user.route.js"
click R4 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/routes/v1/index.js"
click CT1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/controllers/auth.controller.js"
click CT2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/controllers/user.controller.js"
click CT3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/controllers/index.js"
click S1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/services/auth.service.js"
click S2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/services/email.service.js"
click S3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/services/token.service.js"
click S4 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/services/user.service.js"
click S5 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/services/index.js"
click M1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/models/user.model.js"
click M2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/models/token.model.js"
click M3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/models/index.js"
click P1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/models/plugins/paginate.plugin.js"
click P2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/models/plugins/toJSON.plugin.js"
click P3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/models/plugins/index.js"
click MW1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/middlewares/auth.js"
click MW2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/middlewares/error.js"
click MW3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/middlewares/rateLimiter.js"
click MW4 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/middlewares/validate.js"
click CFG1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/config/config.js"
click CFG2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/config/logger.js"
click CFG3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/config/morgan.js"
click CFG4 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/config/passport.js"
click CFG5 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/config/roles.js"
click CFG6 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/config/tokens.js"
click U1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/utils/ApiError.js"
click U2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/utils/catchAsync.js"
click U3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/utils/pick.js"
click D1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/docs/swaggerDef.js"
click D2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/docs/components.yml"
click V1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/validations/auth.validation.js"
click V2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/validations/custom.validation.js"
click V3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/validations/user.validation.js"
click V4 "https://github.com/hagopj13/node-express-boilerplate/blob/master/src/validations/index.js"
click T1 "https://github.com/hagopj13/node-express-boilerplate/blob/master/tests/integration/auth.test.js"
click T2 "https://github.com/hagopj13/node-express-boilerplate/blob/master/tests/integration/docs.test.js"
click T3 "https://github.com/hagopj13/node-express-boilerplate/blob/master/tests/integration/user.test.js"
click T4 "https://github.com/hagopj13/node-express-boilerplate/blob/master/tests/unit/middlewares/error.test.js"
click T5 "https://github.com/hagopj13/node-express-boilerplate/tree/master/tests"
```
