# jekoyu/express_master architecture

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

- Interactive diagram: https://gitdiagram.com/jekoyu/express_master
- Repository: https://github.com/jekoyu/express_master

## Overview

##### Project Type and Purpose
- This is a Node.js/Express REST API service for user account management and authentication (admin & agent roles).
- It follows a layered, modular architecture separating HTTP routing, business logic, data access, configuration, and utilities.

##### File‐Structure Analysis
- Entry point:
- bin/www (HTTP server bootstrap)
- app.js (Express app setup: middleware & routes)
- Configuration:
- /config/*.js (environment‐driven settings: DB, AES, tokens, email, API)
- .env-sample
- Database drivers:
- /database/mysql.connection.js
- /database/redis.connection.js
- Application core (/src):
- /route → Express routes
- /controller → Orchestrate request→response
- /service → Business logic / token generation
- /repository → DB/Redis queries
- /model → Schema definitions (MySQL ORM models)
- /validation → Input schemas
- /constant → Shared enums/values
- Cross-cutting:
- /middleware → Request validators, auth guards, custom headers
- /exception → Structured error classes
- /utility → Helpers (encryption, pagination, formatting)
- Other:
- /dev-notes for DB DDL scripts
- package.json, .gitignore, node_modules

##### Key Architectural Patterns
- Layered (Route → Controller → Service → Repository → Model)
- Dependency Injection via require/import of config and utilities
- Centralized error handling with custom exception types
- Environment‐based configuration

a. External Actors (Clients)
- API Consumers (Web, Mobile, External Systems)
b. API Layer
- Load Balancer / API Gateway (optional)
- Express App
- Middleware (header injector, input validator, JWT guard)
- Routes → Controllers
c. Business Layer
- Services: authService, accountAdminService, tokenService, etc.
d. Data Access Layer
- Repositories: SQL queries (MySQL) and Redis operations
- Models: ORM mappings (account, role, status)
e. Data Stores & External Systems
- MySQL database
- Redis cache/session store
- SMTP/email provider (via email.config)
f. Configuration Subsystem
- Config modules reading from .env (db.config, token.config, aes.config)
g. Utility Modules
- Encryption, pagination, metadata, response formatting

##### Interactions & Data Flow
1. Client → HTTP request → Express app
2. Middleware chain (UTC header → request validation → token auth)
3. Router dispatch → Controller method
4. Controller calls Service
5. Service enforces business rules, calls Repository for persistence/caching
6. Repository uses MySQL/Redis drivers
7. Service returns result to Controller → formatted via response-API utility
8. Controller sends HTTP response
9. Errors bubble up to central error handler using custom exception classes
10. Services may trigger external email via configured SMTP

##### Technologies & Frameworks
- Node.js, Express.js
- MySQL (ORM or raw SQL)
- Redis
- JSON Web Token (token.config)
- AES encryption (aes.config & encrypt-decrypt utility)
- dotenv for env vars
- Custom middleware & error classes

##### Essential Elements
- Clear labels on components (e.g., “Auth Controller”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    subgraph "External"
        API_Clients["API Consumers (Web/Mobile)"]:::external
    end

    %% API Gateway / Load Balancer (optional)
    subgraph "API Layer"
        LB["Load Balancer / API Gateway"]:::api
        WWW["HTTP Server Bootstrap\n(bin/www)"]:::api
        App["Express App\n(app.js)"]:::api
        subgraph "Middleware Chain"
            UTC["UTC Header Injector"]:::api
            VALID["Request Validation"]:::api
            JWT["Token Validation (JWT Guard)"]:::api
        end
        subgraph "Routing"
            MainRoute["Main Router\n(route/index.js)"]:::api
            AuthRoute["Auth Routes\n(route/auth.route.js)"]:::api
            AccountRoute["Account Routes\n(route/account.route.js)"]:::api
        end
    end

    %% Controllers
    subgraph "Controllers"
        AuthCtrl["Auth Controller\n(src/controller/auth.controller.js)"]:::api
        AdminCtrl["Account Admin Controller\n(src/controller/account-admin.controller.js)"]:::api
        AgentCtrl["Account Agent Controller\n(src/controller/account-agent.controller.js)"]:::api
    end

    %% Business Layer
    subgraph "Services"
        AuthSvc["Auth Service\n(src/service/auth.service.js)"]:::service
        TokenSvc["Token Service\n(src/service/token.service.js)"]:::service
        AdminSvc["Account Admin Service\n(src/service/account-admin.service.js)"]:::service
        AgentSvc["Account Agent Service\n(src/service/account-agent.service.js)"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access"
        subgraph "Repositories"
            AuthRepo["Auth Repository\n(src/repository/auth.repository.js)"]:::dataaccess
            AdminRepo["Account Admin Repository\n(src/repository/account-admin.repository.js)"]:::dataaccess
            AgentRepo["Account Agent Repository\n(src/repository/account-agent.repository.js)"]:::dataaccess
        end
        subgraph "Models"
            AccountModel["Account Model\n(src/model/mysql/account.model.js)"]:::dataaccess
            StatusModel["Account-Status Model\n(src/model/mysql/account-status.model.js)"]:::dataaccess
            RoleModel["Role Model\n(src/model/mysql/role.model.js)"]:::dataaccess
        end
    end

    %% Data Stores
    subgraph "Data Stores & External Systems"
        MySQL["MySQL Database"]:::datastore
        Redis["Redis Cache/Session Store"]:::datastore
        SMTP["SMTP / Email Provider"]:::external
    end

    %% Configuration Subsystem
    subgraph "Configuration"
        Env[".env-sample"]:::conf
        APIConf["API Config\n(config/api.config.js)"]:::conf
        DBConf["Database Config\n(config/db.config.js)"]:::conf
        AESConf["AES Config\n(config/aes.config.js)"]:::conf
        TokenConf["Token Config\n(config/token.config.js)"]:::conf
        EmailConf["Email Config\n(config/email.config.js)"]:::conf
        MySQLConn["MySQL Connection\n(database/mysql.connection.js)"]:::conf
        RedisConn["Redis Connection\n(database/redis.connection.js)"]:::conf
    end

    %% Utilities and Exceptions
    subgraph "Utilities"
        EncUtil["Encrypt/Decrypt\n(utility/encrypt-decrypt.js)"]:::util
        RespUtil["Response Formatting\n(utility/response-api.js)"]:::util
        ErrFmt["Error Formatting\n(utility/error-format.js)"]:::util
        PagUtil["Pagination Utility\n(utility/pagination.utility.js)"]:::util
        MetaUtil["Metadata Info\n(utility/metadata-info.utility.js)"]:::util
    end

    subgraph "Exceptions"
        ExIndex["Exception Index\n(exception/index.js)"]:::err
        AuthErr["Authentication Error\n(exception/error-authentication.exception.js)"]:::err
        OtherErr["Other Custom Errors\n(exception/*.exception.js)"]:::err
    end

    %% Flows
    API_Clients -->|HTTP Request| LB
    LB --> WWW --> App
    App --> UTC --> VALID --> JWT
    JWT --> MainRoute
    MainRoute --> AuthRoute
    MainRoute --> AccountRoute

    AuthRoute --> AuthCtrl
    AccountRoute --> AdminCtrl
    AccountRoute --> AgentCtrl

    AuthCtrl --> AuthSvc
    AdminCtrl --> AdminSvc
    AgentCtrl --> AgentSvc
    AuthSvc --> TokenSvc

    AuthSvc --> AuthRepo
    AdminSvc --> AdminRepo
    AgentSvc --> AgentRepo

    AuthRepo --> AccountModel
    AuthRepo --> StatusModel
    AuthRepo --> RoleModel
    AdminRepo --> AccountModel
    AdminRepo --> StatusModel
    AgentRepo --> AccountModel
    AgentRepo --> RoleModel

    AuthRepo --> MySQL
    AdminRepo --> MySQL
    AgentRepo --> MySQL
    AuthSvc --> Redis
    TokenSvc --> Redis
    AdminSvc --> SMTP
    AgentSvc --> SMTP

    %% Configuration dependencies
    Env --> APIConf --> DBConf --> MySQLConn --> MySQL
    DBConf --> RedisConn --> Redis
    TokenConf --> TokenSvc
    AESConf --> EncUtil
    EmailConf --> SMTP

    %% Utilities and Exceptions
    AuthCtrl --> RespUtil
    AuthSvc --> EncUtil
    App --> ExIndex
    ExIndex --> AuthErr
    ExIndex --> OtherErr

    %% Click Events
    click WWW "https://github.com/jekoyu/express_master/tree/main/bin/www"
    click App "https://github.com/jekoyu/express_master/blob/main/app.js"
    click Env "https://github.com/jekoyu/express_master/blob/main/.env-sample"
    click APIConf "https://github.com/jekoyu/express_master/blob/main/config/api.config.js"
    click DBConf "https://github.com/jekoyu/express_master/blob/main/config/db.config.js"
    click AESConf "https://github.com/jekoyu/express_master/blob/main/config/aes.config.js"
    click TokenConf "https://github.com/jekoyu/express_master/blob/main/config/token.config.js"
    click EmailConf "https://github.com/jekoyu/express_master/blob/main/config/email.config.js"
    click MySQLConn "https://github.com/jekoyu/express_master/blob/main/database/mysql.connection.js"
    click RedisConn "https://github.com/jekoyu/express_master/blob/main/database/redis.connection.js"
    click MainRoute "https://github.com/jekoyu/express_master/blob/main/route/index.js"
    click AuthRoute "https://github.com/jekoyu/express_master/blob/main/route/auth.route.js"
    click AccountRoute "https://github.com/jekoyu/express_master/blob/main/route/account.route.js"
    click AuthCtrl "https://github.com/jekoyu/express_master/blob/main/src/controller/auth.controller.js"
    click AdminCtrl "https://github.com/jekoyu/express_master/blob/main/src/controller/account-admin.controller.js"
    click AgentCtrl "https://github.com/jekoyu/express_master/blob/main/src/controller/account-agent.controller.js"
    click AuthSvc "https://github.com/jekoyu/express_master/blob/main/src/service/auth.service.js"
    click TokenSvc "https://github.com/jekoyu/express_master/blob/main/src/service/token.service.js"
    click AdminSvc "https://github.com/jekoyu/express_master/blob/main/src/service/account-admin.service.js"
    click AgentSvc "https://github.com/jekoyu/express_master/blob/main/src/service/account-agent.service.js"
    click AuthRepo "https://github.com/jekoyu/express_master/blob/main/src/repository/auth.repository.js"
    click AdminRepo "https://github.com/jekoyu/express_master/blob/main/src/repository/account-admin.repository.js"
    click AgentRepo "https://github.com/jekoyu/express_master/blob/main/src/repository/account-agent.repository.js"
    click AccountModel "https://github.com/jekoyu/express_master/blob/main/src/model/mysql/account.model.js"
    click StatusModel "https://github.com/jekoyu/express_master/blob/main/src/model/mysql/account-status.model.js"
    click RoleModel "https://github.com/jekoyu/express_master/blob/main/src/model/mysql/role.model.js"
    click EncUtil "https://github.com/jekoyu/express_master/blob/main/utility/encrypt-decrypt.js"
    click RespUtil "https://github.com/jekoyu/express_master/blob/main/utility/response-api.js"
    click ErrFmt "https://github.com/jekoyu/express_master/blob/main/utility/error-format.js"
    click PagUtil "https://github.com/jekoyu/express_master/blob/main/utility/pagination.utility.js"
    click MetaUtil "https://github.com/jekoyu/express_master/blob/main/utility/metadata-info.utility.js"
    click ExIndex "https://github.com/jekoyu/express_master/blob/main/exception/index.js"
    click AuthErr "https://github.com/jekoyu/express_master/blob/main/exception/error-authentication.exception.js"

    %% Styles
    classDef external fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef api fill:#add8e6,stroke:#333,stroke-width:1px
    classDef service fill:#90ee90,stroke:#333,stroke-width:1px
    classDef dataaccess fill:#ffa500,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef conf fill:#e6e6fa,stroke:#333,stroke-width:1px
    classDef util fill:#f5f5dc,stroke:#333,stroke-width:1px
    classDef err fill:#ffcccb,stroke:#333,stroke-width:1px
```
