# josefdri/express-ts-clean-arch architecture

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

- Interactive diagram: https://gitdiagram.com/josefdri/express-ts-clean-arch
- Repository: https://github.com/josefdri/express-ts-clean-arch

## Overview

##### Project Type and Purpose
- This is a backend‐only, RESTful API service built with Node.js, Express and TypeScript, following Uncle Bob’s Clean Architecture.
- It exposes endpoints under `/api/employees` to create and list employees, with JWT‐based auth, MongoDB for persistence, and unit tests around the route layer.

##### File Structure & Architectural Layers
- **Core (Domain)**
- `src/domain/models` & `src/domain/usecases`: Business entities (Employee) and use‐case interfaces (addEmployee, loadEmployees, checkToken).
- **Data Layer**
- `src/data/protocols`: Abstractions for cryptography (encrypter/decrypter) and DB repos.
- `src/data/usecases`: Implementations of use‐cases orchestrating protocols.
- **Infra Layer**
- `src/infra/cryptography/jwt`: JWT signing/verification.
- `src/infra/db/mongodb`: MongoDB employee repository.
- `src/infra/usecases`: Glue implementations (e.g., checkToken).
- **Presentation Layer**
- `src/presentation/controllers`: HTTP controllers handling requests/responses.
- `src/presentation/middlewares`: Auth middleware.
- **Entry Point & Wiring (Main)**
- `src/main/config`: Express app setup, middleware, routes.
- `src/main/adapters`: Express‐to‐usecase adapters.
- `src/main/factories`: Composition roots – factories that build controllers, use cases, decorators, middlewares.
- `src/main/server.ts`: Boots the HTTP server.
- **Validation**
- `src/validation/validators`: Request validation logic.

- **External Client**: Browser/Postman (HTTP requests with JWT).
- **API Gateway** (Express Server)
- server.ts → app.ts
- Global middleware (logging, bodyParser)
- **Routing Layer**
- `routes/employee.routes` maps endpoints to controller factories.
- **Middleware**
- Auth‐middleware (JWT verification → `check-token` use case)
- **Controllers** (Presentation)
- `AddEmployeeController` & `LoadEmployeesController`
- Validate input → invoke use case → format HTTP response.
- **Use Cases**
- Domain interface → Data‐layer implementation
- `dbAddEmployee`, `dbLoadEmployee`, `checkToken`
- **Protocols/Repositories**
- `AddEmployeeRepository`, `LoadEmployeeRepository` abstractions
- `MongoEmployeeRepository` (implements both)
- **Cryptography**
- `Encrypter` & `Decrypter` interfaces → `JwtAdapter`
- **Database**
- MongoDB instance
- **Central Domain**
- Entities & pure business rules, isolated from infra.

##### Relationships & Interactions
- HTTP Request → Express → [Global Middleware] → Router
- Router → [Auth Middleware] → Controller
- Controller → Validation → Use Case (injected impl)
- Use Case → Protocols (e.g., repo, crypto)
- Protocol Impl → External resources (MongoDB, JWT lib)
- Response bubbles back through layers.

##### Architectural Patterns & Principles
- **Clean Architecture**: Concentric layers, dependencies point inwards.
- **Dependency Inversion**: Controllers/use‐cases depend on abstractions.
- **Factory Pattern**: `main/factories` builds and wires all dependencies.
- **Decorator Pattern**: Logging decorator wraps controllers.
- **Singleton**: Shared adapters (e.g., one DB client).
- **SOLID**: Each layer has a single responsibility; open for extension.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    Client["External Client\n(Browser/Postman)"]:::external

    %% API Gateway
    APIGateway["Express Server\n(server.ts, app.ts)"]:::main

    %% Global Middleware
    MW_Global["Global Middleware\n(logging, bodyParser)"]:::main

    %% Routes
    Routes["Employee Routes\n(employee.routes)"]:::main

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        AuthMW["Auth Middleware\n(auth-middleware.ts)"]:::presentation
        AddCtrl["AddEmployeeController"]:::presentation
        LoadCtrl["LoadEmployeesController"]:::presentation
        Validation["Request Validation"]:::presentation
    end

    %% Use Cases Layer (Domain Interfaces)
    subgraph "Domain Layer"
        direction TB
        DomainModel["Employee Model"]:::domain
        AddUC["AddEmployee Interface"]:::domain
        LoadUC["LoadEmployees Interface"]:::domain
        CheckTokenUC["CheckToken Interface"]:::domain
    end

    %% Data & Protocols Layer
    subgraph "Data & Protocols Layer"
        direction TB
        EncrypterProto["Encrypter Interface"]:::data
        DecrypterProto["Decrypter Interface"]:::data
        AddRepoProto["AddEmployeeRepository"]:::data
        LoadRepoProto["LoadEmployeeRepository"]:::data
        DBAddUC["DB AddEmployee UseCase"]:::data
        DBLoadUC["DB LoadEmployees UseCase"]:::data
    end

    %% Infra Layer
    subgraph "Infra Layer"
        direction TB
        JwtAdapter["JwtAdapter"]:::infra
        MongoRepo["MongoEmployeeRepository"]:::infra
        MongoHelper["MongoDB Helper"]:::infra
        CheckTokenImpl["CheckToken Implementation"]:::infra
    end

    %% Main / Factories
    subgraph "Main & Factories"
        direction TB
        ControllersFactory["Controller Factories"]:::main
        UseCasesFactory["UseCase Factories"]:::main
        MiddlewareFactory["Middleware Factory"]:::main
        DecoratorFactory["Decorator Factory"]:::main
        ValidationFactory["Validation Factory"]:::main
        Adapters["Express Adapters"]:::main
        Config["App Config & Server"]:::main
    end

    %% External Infra
    subgraph "External Services"
        direction TB
        JWTService["JWT Library"]:::external
        MongoDB["MongoDB Instance"]:::external
    end

    %% Connections
    Client --> APIGateway
    APIGateway --> MW_Global
    MW_Global --> Routes
    Routes --> AuthMW
    AuthMW --> AddCtrl
    AuthMW --> LoadCtrl
    AddCtrl --> Validation
    LoadCtrl --> Validation
    Validation --> AddUC
    Validation --> LoadUC
    AddUC --> DBAddUC
    LoadUC --> DBLoadUC
    AddUC --> EncrypterProto
    AddUC --> DecrypterProto
    DBAddUC --> AddRepoProto
    DBLoadUC --> LoadRepoProto
    EncrypterProto --> JwtAdapter
    DecrypterProto --> JwtAdapter
    AddRepoProto --> MongoRepo
    LoadRepoProto --> MongoRepo
    JwtAdapter --> JWTService
    MongoRepo --> MongoHelper
    MongoHelper --> MongoDB
    CheckTokenUC --> CheckTokenImpl
    CheckTokenImpl --> JwtAdapter

    %% Factory Wiring
    ControllersFactory --> AddCtrl
    ControllersFactory --> LoadCtrl
    UseCasesFactory --> DBAddUC
    UseCasesFactory --> DBLoadUC
    UseCasesFactory --> CheckTokenImpl
    MiddlewareFactory --> AuthMW
    DecoratorFactory --> AddCtrl
    DecoratorFactory --> LoadCtrl
    ValidationFactory --> Validation
    Adapters --> AddCtrl
    Adapters --> AuthMW
    Config --> APIGateway

    %% Click Events
    click DomainModel "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/domain/models/employee.ts"
    click AddUC "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/domain/usecases/add-employee.ts"
    click LoadUC "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/domain/usecases/load-employees.ts"
    click CheckTokenUC "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/domain/usecases/check-token.ts"
    click EncrypterProto "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/data/protocols/cryptography/encrypter.ts"
    click DecrypterProto "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/data/protocols/cryptography/decrypter.ts"
    click AddRepoProto "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/data/protocols/db/employee/add-employee-repository.ts"
    click LoadRepoProto "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/data/protocols/db/employee/load-employee.ts"
    click DBAddUC "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/data/usecases/db-add-employee.ts"
    click DBLoadUC "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/data/usecases/db-load-employee.ts"
    click JwtAdapter "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/infra/cryptography/jwt.ts"
    click MongoRepo "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/infra/db/mongodb/employee-repository.ts"
    click MongoHelper "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/infra/db/mongodb/helper.ts"
    click CheckTokenImpl "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/infra/usecases/check-token.ts"
    click AddCtrl "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/presentation/controllers/add-employees.controller.ts"
    click LoadCtrl "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/presentation/controllers/load-employees.controller.ts"
    click AuthMW "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/presentation/middlewares/auth-middleware.ts"
    click Validation "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/validation/validators/required-field-validation.ts"
    click Validation "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/validation/validators/validation-composite.ts"
    click Config "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/config/app.ts"
    click Config "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/config/middlewares.ts"
    click Config "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/config/routes.ts"
    click Adapters "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/adapters/express-route-adapter.ts"
    click Adapters "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/adapters/express-middleware-adapter.ts"
    click ControllersFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/controllers/add-employee-controller.factory.ts"
    click ControllersFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/controllers/load-employee-controller.factory.ts"
    click UseCasesFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/usecases/add-employee-factory.ts"
    click UseCasesFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/usecases/load-employee-factory.ts"
    click UseCasesFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/usecases/check-auth-factory.ts"
    click MiddlewareFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/middlewares/auth-middleware-factory.ts"
    click DecoratorFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/decorators/log-controller-decorator-factory.ts"
    click ValidationFactory "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/factories/validations/add-employee-validation-factory.ts"
    click Routes "https://github.com/josefdri/express-ts-clean-arch/blob/main/src/main/routes/employee.routes.ts"

    %% Styles
    classDef domain fill:#D6E9F8,stroke:#4DA1DE,color:#000
    classDef data fill:#DFF5E1,stroke:#7FC97F,color:#000
    classDef infra fill:#FFE6C7,stroke:#FDAE61,color:#000
    classDef presentation fill:#E5D7FF,stroke:#9B59B6,color:#000
    classDef main fill:#E8E8E8,stroke:#A0A0A0,color:#000
    classDef external fill:#F0F0F0,stroke:#AAA,color:#000
```
