# apuy717/template-api architecture

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

- Interactive diagram: https://gitdiagram.com/apuy717/template-api
- Repository: https://github.com/apuy717/template-api

## Overview

##### Project Type and Purpose
- This is a Node.js TypeScript–based REST API template (“template-api”) that accelerates API development.
- It uses Express under the hood (via decorators), TypeORM for data access, JWT for auth, and supports RBAC, clustering, request validation, and OpenAPI docs.

##### Main Architectural Components
a. Entry & HTTP Layer
- server.ts: Starts an HTTP server, sets up clustering.
- app.ts: Initializes Express app, registers middleware, routes, error handlers.
b. Routing & Controllers
- src/controllers/*.controller.ts: Define decorated route handlers (AuthController, UserController, RoleController).
c. Middleware
- src/middlewares/auth.middleware.ts: JWT verification & RBAC enforcement.
- Decorator layer in src/utils/decorators for mapping controllers/middlewares.
d. Business Logic Layer
- src/services/*.service.ts: Encapsulate core operations (auth, user, role, permission).
e. Data Access Layer
- src/database/datasource.ts: TypeORM DataSource config.
- src/models/*.entity.ts: Entity definitions for User, Role, Permission.
- src/database/migrations: Schema migrations.
f. DTOs & Validation
- src/validators & helper.validator.ts: Input validation logic.
g. API Documentation
- openapi.yaml + docs/: Auto-generated Swagger/OpenAPI definitions.
h. Testing
- tests/app.e2e.test.ts: End-to-end test suite via Mocha.
i. Utilities & Config
- .env.example, package.json, tsconfig.json, mocha.config.json.

##### Component Interactions & Data Flow
1. Client HTTP Request → Express cluster (server.ts spawns workers).
2. Worker Express App (app.ts) → Global Middleware (logging, JSON parsing).
3. Authentication Middleware → Verifies JWT, loads roles/permissions.
4. Routing Decorator Layer → Dispatch to correct Controller method.
5. Controller → Input is validated against DTOs.
6. Controller → Calls corresponding Service.
7. Service → Uses TypeORM Repositories (DataSource) to interact with Database.
8. Service → Business logic (create user, assign roles, generate JWT).
9. Service → Returns result to Controller.
10. Controller → Sends HTTP response.
11. Swagger UI via /api-docs reads openapi.yaml.

##### Architectural Patterns & Principles
- Layered MVC-style architecture: Controllers → Services → Repositories (TypeORM).
- Decorator-driven routing and middleware (separation of concerns, declarative).
- RBAC enforced at middleware layer.
- Clustering to leverage multi-core CPUs.
- Migration-based schema evolution.

##### Practical Steps
2. Inside each Worker: stack three horizontal layers:
- Layer 1: “Express App” → “Global Middleware” → “Auth & RBAC Middleware”.
- Layer 2: “Decorator Router” → “Controllers [Auth, User, Role]”.
- Layer 3: “Services [AuthService, UserService, RoleService, PermissionService]”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Cluster and Workers
    CM["Cluster Manager"]:::process
    WP["Worker Process (n)"]:::process
    CM -->|spawns| WP
    click CM "https://github.com/apuy717/template-api/blob/master/src/server.ts"

    subgraph "Worker Process"
        direction TB
        %% Layer 1: HTTP & Middleware
        subgraph "Layer 1: HTTP & Middleware"
            direction TB
            EA["Express App"]:::process
            GM["Global Middleware"]:::middleware
            AuthM["Auth & RBAC Middleware"]:::middleware
        end
        click EA "https://github.com/apuy717/template-api/blob/master/src/app.ts"
        click AuthM "https://github.com/apuy717/template-api/blob/master/src/middlewares/auth.middleware.ts"
        click GM "https://github.com/apuy717/template-api/blob/master/src/utils/decorators/middleware.decorator.ts"

        %% Layer 2: Routing, Decorators & Controllers
        subgraph "Layer 2: Routing & Controllers"
            direction TB
            subgraph "Decorator Layer"
                CDec["Controller Decorator"]:::router
                HDec["Handler Decorator"]:::router
                MDec["Middleware Decorator"]:::router
                MK["Metadata Keys"]:::router
            end
            AC["AuthController"]:::controller
            UC["UserController"]:::controller
            RC["RoleController"]:::controller
        end
        click CDec "https://github.com/apuy717/template-api/blob/master/src/utils/decorators/controller.decorator.ts"
        click HDec "https://github.com/apuy717/template-api/blob/master/src/utils/decorators/handler.decorator.ts"
        click MDec "https://github.com/apuy717/template-api/blob/master/src/utils/decorators/middleware.decorator.ts"
        click MK "https://github.com/apuy717/template-api/blob/master/src/utils/metadata.keys.ts"
        click AC "https://github.com/apuy717/template-api/blob/master/src/controllers/auth.controller.ts"
        click UC "https://github.com/apuy717/template-api/blob/master/src/controllers/user.controller.ts"
        click RC "https://github.com/apuy717/template-api/blob/master/src/controllers/role.controller.ts"

        %% Layer 3: Services
        subgraph "Layer 3: Services"
            direction TB
            AuthS["AuthService"]:::service
            UserS["UserService"]:::service
            RoleS["RoleService"]:::service
            PermS["PermissionService"]:::service
        end
        click AuthS "https://github.com/apuy717/template-api/blob/master/src/services/auth.service.ts"
        click UserS "https://github.com/apuy717/template-api/blob/master/src/services/user.service.ts"
        click RoleS "https://github.com/apuy717/template-api/blob/master/src/services/role.service.ts"
        click PermS "https://github.com/apuy717/template-api/blob/master/src/services/permission.service.ts"
    end

    %% DTOs & Validation
    subgraph "DTOs & Validation"
        direction TB
        LoginDTO["Login DTO"]:::dto
        RoleDTO["Role Create DTO"]:::dto
        UserDTO["User Create/Update DTO"]:::dto
        Validator["Validation Helpers"]:::validation
    end
    click LoginDTO "https://github.com/apuy717/template-api/blob/master/src/dtos/auth.login.dto.ts"
    click RoleDTO "https://github.com/apuy717/template-api/blob/master/src/dtos/roles.create.dto.ts"
    click UserDTO "https://github.com/apuy717/template-api/blob/master/src/dtos/user.create.update.dto.ts"
    click Validator "https://github.com/apuy717/template-api/blob/master/src/validators/helper.validator.ts"

    %% Data Access Layer
    DS["TypeORM DataSource"]:::dbconfig
    subgraph "Entities & Migrations"
        direction TB
        UserE["User Entity"]:::database
        RoleE["Role Entity"]:::database
        PermE["Permission Entity"]:::database
        Migrations["Migrations"]:::external
    end
    click DS "https://github.com/apuy717/template-api/blob/master/src/database/datasource.ts"
    click UserE "https://github.com/apuy717/template-api/blob/master/src/models/user.entity.ts"
    click RoleE "https://github.com/apuy717/template-api/blob/master/src/models/roles.entity.ts"
    click PermE "https://github.com/apuy717/template-api/blob/master/src/models/permission.entity.ts"
    click Migrations "https://github.com/apuy717/template-api/blob/master/src/database/migrations/1747589927044-migration.ts"

    DB["Database"]:::database

    %% Documentation & External
    Swagger["Swagger UI"]:::external
    click Swagger "https://github.com/apuy717/template-api/blob/master/openapi.yaml"

    %% Flows
    WP --> EA
    EA --> GM --> AuthM --> CDec
    CDec --> AC -->|"validate DTO"| LoginDTO
    AC --> UserDTO
    AC --> RoleDTO
    AC --> AuthS
    UC --> UserS
    RC --> RoleS
    AuthS --> DS --> DB
    UserS --> DS
    RoleS --> DS
    PermS --> DS
    DS -->|migrate| Migrations
    Swagger -->|"reads spec"| openapi.yaml

    %% Styles
    classDef process fill:#fde2e2,stroke:#e63946,stroke-width:2px
    classDef middleware fill:#e2f0cb,stroke:#558b2f,stroke-width:1px
    classDef router fill:#fff3b0,stroke:#f9a825,stroke-width:1px
    classDef controller fill:#ffd8be,stroke:#ff5722,stroke-width:1px
    classDef service fill:#ffecb3,stroke:#fbc02d,stroke-width:1px
    classDef dbconfig fill:#c5cae9,stroke:#303f9f,stroke-width:1px
    classDef database fill:#bbdefb,stroke:#1976d2,stroke-width:1px
    classDef external fill:#f0f4c3,stroke-dasharray:5 5,stroke:#827717
    classDef dto fill:#fce4ec,stroke:#c2185b,stroke-width:1px
    classDef validation fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px
```
