# robbecl/boilerplate-express-typescript-sequelize architecture

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

- Interactive diagram: https://gitdiagram.com/robbecl/boilerplate-express-typescript-sequelize
- Repository: https://github.com/robbecl/boilerplate-express-typescript-sequelize

## Overview

##### Project type and purpose
- This is a boilerplate full-stack back-end service built with Node.js, Express, TypeScript, and Sequelize.
- Its purpose is to serve as a production-ready REST API (and minimal server-rendered pages via Pug), with built-in authentication, role management, session/refresh-token support, email templating, logging, Swagger docs, Docker deployment, migrations, and seeding.

##### File structure
- Top-level configs: Dockerfile, docker-compose.yml, .env.example, tsconfig.json, Babel, ESLint, Prettier, Husky, Commitlint.
- src/
- config/: database, Redis, email, logger, HTTP client, base URLs
- controllers/ → routers/controllers per resource (Auth, User, Role, Session, RefreshToken, UserRole)
- services are alongside controllers (service.ts)
- middlewares/: authorization, transaction handler, error handlers
- models/, migrations/, seeders/ → Sequelize ORM layer
- helpers/, modules/, utils/ → shared libraries (file uploads, Excel, email sender, token helpers, response builders, query helpers)
- routes/: public vs index (mount point)
- views/: Pug templates for error pages and index
- public/: static CSS, email HTML templates
- docs/swagger/: OpenAPI route definitions
- jobs/: scheduled tasks (RoleJob)
- Other directories: logs/, storage (via Docker volume), scripts/ for generating JWT env vars.

##### README
- Confirms technical stack: Node 10+, TS 4.x, Sequelize 6.x, Nodemailer, Handlebars, Yup, Swagger, Winston, Docker.
- Usage patterns: dev vs production, migrations, seeding, Docker compose with three services (app, db, redis), external SMTP or Mailgun/Gmail, cron jobs.

a. Main components
- Clients:
- API Consumers (Postman, browser apps)
- Swagger UI for docs
- Cron scheduler triggering jobs internally
- Load Balancer / Reverse Proxy (optional, e.g., Nginx)
- Express Application container
- HTTP Server (src/bin/server.ts)
- Route Dispatcher → middleware chain → controllers → services
- Business Services (Auth, User, Role, Session, RefreshToken, UserRole)
- Helper/Module Layer (email sender, query helper, token utils, response builder)
- Scheduled Jobs (RoleJob, index.ts in jobs/)
- Static public folder & Pug view renderer
- Data Stores
- MySQL/MariaDB (Sequelize ORM layer: models, migrations, seeders)
- Redis (session cache, token blacklist, rate-limit store)
- External Services
- SMTP/mail service (Mailgun or Google OAuth2)
- Redis cluster if scaled
- Optional S3 or file storage for uploads
- DevOps / Infrastructure
- Docker Compose network with three services: express_app, express_db, express_redis
- CI/CD (Husky, Commitlint, release scripts)
- Logging to filesystem via Winston

b. Relationships and interactions
- Client → HTTP request → Express /routes/ → middlewares → controllers
- Controller invokes service layer → modules/helpers → Sequelize → MySQL
- Service may read/write Redis via config/Rediss.ts
- Service may dispatch email via Nodemailer + Handlebars templates
- Scheduled Jobs run inside the same container, using service layer to operate on DB
- Swagger UI served by express at /docs
- Migrations/seeders executed via npm scripts before startup
- Docker Compose orchestrates network communication

c. Architectural patterns & principles
- Layered architecture: Presentation (routes/controllers), Business (services), Data Access (models, Sequelize)
- Dependency Injection via config modules
- Transaction management via middleware (ExpressAutoHandleTransaction)
- OpenAPI-first docs generation
- CQRS-ish separation: controllers handle HTTP, services handle logic, modules/utilities handle cross-cutting concerns
- Error-first flow: custom error classes and centralized error handler

d. Key technologies
- Node.js + Express + TypeScript
- Sequelize ORM + MariaDB
- Redis for cache/session management
- Nodemailer + Handlebars for email templating
- Winston for logging
- Yup for request validation
- Swagger for API docs
- Docker + Docker Compose for environment isolation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        API_Consumer["API Consumers (Postman, Browser)"]:::client
        Swagger_UI["Swagger UI"]:::client
        Cron_Scheduler["Cron Scheduler"]:::client
    end

    %% Infrastructure Layer
    subgraph "Infrastructure" 
        LB["Load Balancer / Reverse Proxy (Nginx)"]:::infra
        Docker_Compose["Docker Compose Network"]:::infra
        CI_CD["CI/CD & Linting"]:::infra
    end

    %% Express Application Container
    subgraph "Express App Container" 
        direction TB
        HTTP_Server["HTTP Server Entry Point"]:::api
        ExpressAppInit["Express Application Initialization"]:::api

        subgraph "Routing"
            direction TB
            PublicRoutes["Public Routes"]:::api
            MainRouter["Main Router"]:::api
        end

        subgraph "Middleware Pipeline"
            direction TB
            AuthMW["Authorization Middleware"]:::api
            TxMW["Transaction Handler Middleware"]:::api
            SeqErrorMW["Sequelize Error Handler"]:::api
            YupErrorMW["Yup Validation Error Handler"]:::api
            GenErrorMW["General Error Handler"]:::api
        end

        subgraph "Controllers & Services"
            direction TB
            subgraph "Auth"
                AuthController["Auth Controller"]:::api
                AuthService["Auth Service"]:::api
            end
            subgraph "User"
                UserController["User Controller"]:::api
                UserService["User Service"]:::api
            end
            subgraph "Role"
                RoleController["Role Controller"]:::api
                RoleService["Role Service"]:::api
            end
            subgraph "Session"
                SessionController["Session Controller"]:::api
                SessionService["Session Service"]:::api
            end
            subgraph "RefreshToken"
                RTController["RefreshToken Controller"]:::api
                RTService["RefreshToken Service"]:::api
            end
            subgraph "UserRole"
                URService["UserRole Service"]:::api
            end
        end

        subgraph "Helpers & Modules"
            direction TB
            FileUpload["File Uploads Helper"]:::util
            EmailSender["Email Sender Helper"]:::util
            TokenUtils["Token Utilities"]:::util
            ValidationWrap["Validation Wrapper"]:::util
            AsyncHandler["Async Handler"]:::util
            ErrorClasses["Error Classes & BaseResponse"]:::util
            ResponseBuilder["Response Builder"]:::util
            SQLHelpers["SQL Query Helpers"]:::util
        end

        subgraph "Sequelize ORM Layer"
            direction TB
            Models["Models"]:::data
            Migrations["Migrations"]:::data
            Seeders["Seeders"]:::data
        end

        subgraph "Scheduled Jobs"
            direction TB
            JobRegistry["Job Registration"]:::job
            RoleJob["RoleJob Task"]:::job
        end

        Swagger_UI_App["Swagger UI (served at /docs)"]:::api
        Static_Public["Static Assets & Views"]:::api
    end

    %% Data Stores Layer
    subgraph "Data Stores"
        DB["MySQL/MariaDB"]:::data
        Redis["Redis"]:::data
    end

    %% External Services Layer
    subgraph "External Services"
        SMTP["SMTP/Mail Service"]:::external
        S3["Optional S3/File Storage"]:::external
    end

    %% CI/CD & Linting
    subgraph "CI/CD & Lint"
        Husky["Husky Hooks"]:::infra
        Commitlint["Commitlint Config"]:::infra
        ESLint["ESLint Config"]:::infra
        Prettier["Prettier Config"]:::infra
    end

    %% Container & Infra connections
    API_Consumer -->|HTTP Request| LB
    Swagger_UI -->|HTTP Request| LB
    Cron_Scheduler -->|Trigger Jobs| HTTP_Server

    LB --> HTTP_Server
    HTTP_Server --> ExpressAppInit
    ExpressAppInit --> PublicRoutes
    ExpressAppInit --> MainRouter

    MainRouter --> AuthMW
    MainRouter --> TxMW
    AuthMW --> SeqErrorMW
    SeqErrorMW --> YupErrorMW
    YupErrorMW --> GenErrorMW
    GenErrorMW --> AuthController
    GenErrorMW --> UserController
    GenErrorMW --> RoleController
    GenErrorMW --> SessionController
    GenErrorMW --> RTController
    GenErrorMW --> URService

    AuthController --> AuthService
    UserController --> UserService
    RoleController --> RoleService
    SessionController --> SessionService
    RTController --> RTService

    AuthService -->|Queries| Models
    UserService -->|Queries| Models
    RoleService -->|Queries| Models
    SessionService -->|Queries| Models
    RTService -->|Queries| Models
    URService -->|Queries| Models

    Models --> DB
    SeqErrorMW --> DB
    AuthService --> Redis
    SessionService --> Redis
    RTService --> Redis

    AuthService --> EmailSender
    EmailSender --> SMTP

    ExpressAppInit --> Swagger_UI_App
    ExpressAppInit --> Static_Public
    ExpressAppInit --> JobRegistry
    JobRegistry --> RoleJob
    RoleJob --> AuthService

    Docker_Compose --> DB
    Docker_Compose --> Redis
    Docker_Compose --> HTTP_Server
    CI_CD --> Husky
    CI_CD --> Commitlint
    CI_CD --> ESLint
    CI_CD --> Prettier

    %% Click Events
    click HTTP_Server "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/bin/server.ts"
    click ExpressAppInit "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/app.ts"
    click DBConfig "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/config/database.ts"
    click RedisConfig "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/config/Rediss.ts"
    click EmailConfig "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/config/email.ts"
    click HTTPClientConfig1 "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/config/Fetcher.ts"
    click HTTPClientConfig2 "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/config/baseURL.ts"
    click Logger "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/config/winston.ts"
    click PublicRoutes "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/routes/public.ts"
    click MainRouter "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/routes/index.ts"
    click AuthMW "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/middlewares/Authorization.ts"
    click TxMW "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/middlewares/ExpressAutoHandleTransaction.ts"
    click SeqErrorMW "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/middlewares/ExpressErrorSequelize.ts"
    click YupErrorMW "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/middlewares/ExpressErrorYup.ts"
    click GenErrorMW "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/middlewares/ExpressErrorResponse.ts"
    click AuthController "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/Auth/controller.ts"
    click AuthService "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/Auth/service.ts"
    click UserController "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/User/controller.ts"
    click UserService "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/User/service.ts"
    click RoleController "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/Role/controller.ts"
    click RoleService "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/Role/service.ts"
    click SessionController "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/Session/controller.ts"
    click SessionService "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/Session/service.ts"
    click RTController "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/RefreshToken/controller.ts"
    click RTService "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/RefreshToken/service.ts"
    click URService "https://github.com/robbecl/boilerplate-express-typescript-sequelize/blob/master/src/controllers/UserRole/service.ts"

    %% Styles
    classDef client fill:#D6E9FE,stroke:#4A90E2,stroke-width:1px
    classDef infra fill:#F2F2F2,stroke:#A0A0A0,stroke-width:1px
    classDef api fill:#E8F5FF,stroke:#5DADE2,stroke-width:1px
    classDef data fill:#E8F9F1,stroke:#28B463,stroke-width:1px
    classDef external fill:#FEF5E7,stroke:#F39C12,stroke-width:1px
    classDef util fill:#F6EBF2,stroke:#9B59B6,stroke-width:1px
    classDef job fill:#FFF5E5,stroke:#D35400,stroke-width:1px
    class CI_CD,Husky,Commitlint,ESLint,Prettier infra
```
