# nguyenchanhdat/boilerplate-ts-clean-architecture architecture

> Architecture diagram of the GitHub repository nguyenchanhdat/boilerplate-ts-clean-architecture, 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/nguyenchanhdat/boilerplate-ts-clean-architecture
- Repository: https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture

## Overview

##### Project Type & Purpose
- The project is a simple ToDo List application built as a boilerplate with Clean Architecture in mind.
- It is structured to separate concerns across layers like application, domain, infrastructure, and presentation.
- The README also indicates support for unit testing, and the use of Docker for containerizing the API, the database (and related tools like Debezium, Kafka, Zookeeper), and the usage of technologies such as TypeORM and TypeScript.

##### Analyzing the File Structure
- At the top level, you have organization via:
▪ Source code under the "src" directory which is further divided into:
- application (DTOs, services, and use-cases defining business logic and input/output contracts)
- domain (entities and repositories specifying core business models)
- infra (database configurations, repository implementations using TypeORM, factory and locator patterns, and security handling)
- presentation (which includes bootstrapping for both REST and gRPC endpoints, controllers, and routes)
▪ Dockerfiles (multiple Dockerfiles for API, database, Debezium, Kafka, Zookeeper) indicating separate container orchestration.
▪ Tests are organized under the __test__ folder.
- Notice that the project cleanly separates concerns. This points directly to Clean Architecture’s separation, where the inner domain remains independent of outer concerns like frameworks and infrastructure.

##### Main Components
a. Presentation Layer:
- REST Controllers (e.g., UserController in the "src/presentation/rest/controllers/user" directory)
- gRPC Services/Controllers (present in "src/presentation/grpc")
- Bootstrapping (ServiceLocator, IBootstrap)
- These components receive the external requests (HTTP/gRPC) from clients (e.g., web/mobile clients).

b. Application Layer:
- Use Cases (e.g., CreateUser, DeleteUser, LoginServices found in "src/application/use-cases")
- DTOs (data transfer objects under "src/application/dto")
- Application Services (business logic interfaces and implementations in "src/application/services")
- This layer coordinates business rules and operations, serving as the mediator between presentation and domain.

c. Domain Layer:
- Domain Entities (User, Plan, Exercise, BodyTrack, Set found in "src/domain/entities")
- Domain Repositories (interfaces defined in "src/domain/repositories")
- This is the core layer containing business models and abstract definitions of storage mechanisms.

d. Infrastructure Layer:
- Database Configuration (config files and various data source bootstrapping modules in "src/infra/databases")
- Repository Implementations (both InMemory and TypeORM based repositories that implement the domain repository interfaces)
- Factory and Global Locators (found in "src/infra/factory" and "src/infra/locator")
- Security modules (like Bcrypt implementation)
- This layer acts as the implementation details that persist or communicate with external systems (e.g., relational databases).

e. Docker & External Services:
- Docker containers for API, Database, Kafka, Zookeeper, and Debezium hint at a distributed environment and possible future integration for CDC (change-data-capture) or streaming use-cases.
- These components can be illustrated as external nodes that interact with the Infra layer (e.g., the database container is accessed via the TypeORM data source).

##### Relationships and Interactions
- From Presentation, the requests are handled by Controllers which then invoke the appropriate Application Services/Use Cases.
- The Application Layer then interacts with the Domain Layer to read/write domain entities.
- Domain Layer depends on repository interfaces that are implemented by components in the Infrastructure Layer.
- The Infrastructure makes external calls to the Database containers (and possibly message brokers).
- Optionally, include interactions for unit testing (the test layer invoking use cases and services).

##### Architectural Patterns & Design Principles
- Clean Architecture: Emphasize how the inner application logic (Domain and Application layers) remains isolated from outer concerns (Presentation, Infrastructure).
- Dependency Inversion: Show that the high-level modules (use cases) depend on abstractions (interfaces) that are then implemented by Infra.

##### Technologies, Frameworks, & Libraries
- TypeScript (primary language for all layers)
- TypeORM (for database communication in the Infrastructure layer)
- Docker (containerization with multiple Dockerfiles)
- gRPC & Express (for gRPC and REST endpoints respectively)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Global Client
    Client["Client"]:::client

    %% Presentation Layer
    subgraph "Presentation Layer"
        PC["UserController (REST)"]:::presentation
        GRPCProto["gRPC Protos"]:::presentation
        GRPCService["gRPC Services"]:::presentation
        SL["ServiceLocator"]:::presentation
        IB["IBootstrap"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        DTO["DTOs"]:::application
        UC["Use Cases"]:::application
        AS["Application Services"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        DE["Domain Entities"]:::domain
        DR["Domain Repositories"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DBC["Database Configuration"]:::infrastructure
        DS["Database DataSources"]:::infrastructure
        RI["Repository Implementations"]:::infrastructure
        DF["Database Factory"]:::infrastructure
        GL["Global Locators"]:::infrastructure
        BM["Security Module (Bcrypt)"]:::infrastructure
    end

    %% External Services
    subgraph "External Services"
        DA["API Container"]:::external
        DDB["Database Container"]:::external
        DBE["Debezium Container"]:::external
        DK["Kafka Container"]:::external
        DZ["Zookeeper Container"]:::external
    end

    %% Connections from Client to Presentation
    Client -->|"HTTP/gRPC"| PC
    Client -->|"HTTP/gRPC"| GRPCProto
    Client -->|"HTTP/gRPC"| GRPCService

    %% Connections from Presentation to Application
    PC -->|"calls"| UC
    GRPCProto -->|"triggers"| UC
    GRPCService -->|"triggers"| UC
    SL -->|"initializes"| AS
    IB -->|"boots"| AS
    PC ---|"may delegate"| SL
    PC ---|"may delegate"| IB

    %% Internal Presentation to Application shared connections
    UC -->|"uses"| DTO

    %% Connections from Application to Domain
    UC -->|"executes"| DR
    AS -->|"coordinates"| DR

    %% Connections within Domain Layer
    DR ---|"manages"| DE

    %% Connections from Domain to Infrastructure
    DR -->|"implemented by"| RI

    %% Connections within Infrastructure Layer
    RI -->|"configured by"| DBC
    RI -->|"accesses"| DS
    RI -->|"factored by"| DF
    DF --> GL
    AS -->|"secures via"| BM

    %% Connections from Infrastructure to External Services
    DBC -->|"connects to"| DDB
    DS -->|"connects to"| DDB
    RI -->|"publishes to"| DBE
    RI -->|"publishes to"| DK
    RI -->|"monitored by"| DZ
    GL -->|"provides access to"| AS

    %% Click Events for Presentation Layer
    click PC "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/presentation/rest/controllers/user/UserController.ts" "UserController Source"
    click GRPCProto "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/presentation/grpc/proto/com/createUser/v1/UserDto.proto" "gRPC Protos Source"
    click GRPCService "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/presentation/grpc/proto/services/createUser/v1/CreateUserService.proto" "gRPC Services Source"
    click SL "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/presentation/bootstrap/ServiceLocator.ts" "Service Locator Source"
    click IB "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/presentation/bootstrap/IBootstrap.ts" "IBootstrap Source"

    %% Click Events for Application Layer
    click DTO "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/application/dto" "DTOs Directory"
    click UC "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/application/use-cases" "Use Cases Directory"
    click AS "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/application/services" "Application Services Directory"

    %% Click Events for Domain Layer
    click DE "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/domain/entities" "Domain Entities Directory"
    click DR "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/domain/repositories" "Domain Repositories Directory"

    %% Click Events for Infrastructure Layer
    click DBC "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/infra/databases/config" "Database Configuration Directory"
    click DS "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/infra/databases/dataSource" "Database DataSources Directory"
    click RI "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/infra/databases/repositories" "Repository Implementations Directory"
    click DF "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/infra/factory/DatabaseFactory.ts" "Database Factory File"
    click GL "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/tree/master/src/infra/locator" "Global Locators Directory"
    click BM "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/src/infra/security/Bcrypt.ts" "Bcrypt Implementation File"

    %% Click Events for External Services
    click DA "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/Dockerfile.api" "Docker API Container File"
    click DDB "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/Dockerfile.db" "Docker Database Container File"
    click DBE "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/Dockerfile.debezium" "Docker Debezium Container File"
    click DK "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/Dockerfile.kafka" "Docker Kafka Container File"
    click DZ "https://github.com/nguyenchanhdat/boilerplate-ts-clean-architecture/blob/master/Dockerfile.zookeeper" "Docker Zookeeper Container File"

    %% Styles
    classDef client fill:#f8c291,stroke:#e67e22,stroke-width:2px;
    classDef presentation fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef application fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef domain fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef infrastructure fill:#f9e79f,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#2ecc71,stroke-width:2px;
```
