How nguyenchanhdat/boilerplate-ts-clean-architecture works
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)