# xalsie/clean-architecture-api-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/xalsie/clean-architecture-api-boilerplate
- Repository: https://github.com/xalsie/clean-architecture-api-boilerplate

## Overview

##### Project Type and Purpose
- This is a backend API service written in TypeScript and Node.js, following Uncle Bob’s Clean Architecture.
- It provides CRUD operations for users (with roles), sign‑in with JWT + refresh tokens, and basic authorization.

##### Core Architectural Layers
a. Domain (Entities): business models (User, Role, Token, Sign‑In).
b. Application (Use Cases): orchestrates use cases (create‑user, sign‑in, refresh‑token, etc.) and defines ports/interfaces for controllers, repositories, validations, etc.
c. Presentation (Interface Adapters): concrete controllers, middleware adapters, and response serializers.
d. Infrastructure (Frameworks & Drivers): Express server, routing, Knex migrations/seeds, SQL repositories.
e. Common (Cross‑cutting Concerns): generic adapters (email validator, bcrypt, JWT, sanitizers), helpers.
f. Main (Composition Root): factory functions wiring together controllers, use cases, repositories, middlewares.

##### Main Components and Data Flow
- Client → HTTP → Express Routes (infrastructure)
- Receives request, hands off to Express‑route adapters
- Route Adapter → Controller (presentation)
- Transforms HTTP req/res into internal request model
- Controller → Use Case (application)
- Invokes a specific use‑case (e.g., CreateUserUseCase) via its interface
- Performs validation, error handling via application‑layer errors & validation composites
- Use Case ↔ Domain (entities)
- Executes business logic using domain models
- Delegates persistence to repository ports (interfaces in application→repositories)
- Repository Implementation (infrastructure)
- Concrete SQL repositories use Knex to query the database
- Returns domain models or primitives back to use case
- Use Case → Presenter (presentation)
- Returns a response model (status, data) to the controller
- Controller → HTTP Response (infrastructure)
- Serializes to JSON using generic response wrappers

##### External Services
- Postgres/MySQL/SQLite via Knex (SQL migrations and seeds)
- JWT for authentication tokens (common adapters)
- BCrypt for password hashing (common adapter)

##### Architectural Patterns & Principles
- Clean Architecture (layers, dependency inward)
- Ports & Adapters: inner layers define interfaces (“ports”), outer layers implement them (“adapters”)
- Factory pattern in Main layer to assemble dependencies
- Composite & Leaf validators in Application layer
- Single Responsibility & Separation of Concerns

##### Detailed Elements
- Express server and routes → adapter → controller → use case → repository → database
- JWT & password‑hashing security adapters plugged into sign‑in and user‑creation flows
- Validation composites in the application layer before executing use cases
- Factory layer wiring: show main/factories invoking Express setup, global middlewares, and route registration

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client"]:::external

    subgraph "Infrastructure Layer"
        subgraph "Express Layer"
            ExpressServer["Express Server"]:::infrastructure
            ExpressRoutes["Express Routes"]:::infrastructure
            ExpressAdapters["Express Adapters"]:::infrastructure
            ExpressMiddlewares["Express Middlewares"]:::infrastructure
            ExpressSetup["Express Setup"]:::infrastructure
        end
        subgraph "DB & Repositories"
            Knex["Knex (DB, migrations, seeds)"]:::infrastructure
            SQLUserRepo["SQL User Repo"]:::infrastructure
            SQLTokenRepo["SQL Token Repo"]:::infrastructure
            DefaultRepo["Default Repositories"]:::infrastructure
            DB[(Database)]:::external
        end
    end

    subgraph "Presentation Layer"
        Controllers["Controllers"]:::presentation
        Middlewares["Auth Middlewares"]:::presentation
        Responses["Response Serializers"]:::presentation
    end

    subgraph "Application Layer"
        PortsControllers["Port: Controllers"]:::application
        PortsRepos["Port: Repositories"]:::application
        PortsSecurity["Port: Security"]:::application
        PortsValidation["Port: Validation"]:::application
        UseCases["Use Cases"]:::application
        AppErrors["Application Errors"]:::application
        ValidationComp["Validation Composites & Leaves"]:::application
    end

    subgraph "Domain Layer"
        Entities["Domain Entities"]:::domain
    end

    subgraph "Common Layer"
        Sanitizers["Sanitizers"]:::common
        SecurityAdapters["Security Adapters"]:::common
        Validators["Email Validators"]:::common
        Helpers["Helpers"]:::common
    end

    subgraph "Main (Composition Root)"
        ControllerFactories["Controller Factories"]:::main
        MiddlewareFactories["Middleware Factories"]:::main
        AppWiring["App Wiring"]:::main
    end

    Client -->|HTTP Request| ExpressRoutes
    ExpressRoutes -->|route to adapter| ExpressAdapters
    ExpressAdapters -->|calls| Controllers
    Controllers -->|to port| PortsControllers
    PortsControllers -->|invoke| UseCases
    ValidationComp -->|validate| UseCases
    UseCases -->|business logic| Entities
    UseCases -->|repo port| PortsRepos
    PortsRepos -->|impl| SQLUserRepo
    PortsRepos -->|impl| SQLTokenRepo
    SQLUserRepo -->|queries| DB
    SQLTokenRepo -->|queries| DB
    Knex -->|migrations/seeds| DB
    UseCases -->|security port| PortsSecurity
    PortsSecurity -->|uses| SecurityAdapters
    UseCases -->|validation port| PortsValidation
    PortsValidation -->|uses| ValidationComp
    Controllers -->|serialize| Responses
    Controllers -->|auth| Middlewares
    ControllerFactories -->|setup| ExpressSetup
    ExpressSetup -->|configures| ExpressServer
    ExpressServer -->|hosts| ExpressRoutes
    MiddlewareFactories -->|setup| ExpressMiddlewares
    AppWiring -->|init| ControllerFactories
    AppWiring -->|init| MiddlewareFactories
    AppWiring -->|init| ExpressSetup

    click Entities "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/domain/models"
    click PortsControllers "https://github.com/xalsie/clean-architecture-api-boilerplate/blob/main/src/application/ports/controllers/controller.ts"
    click PortsRepos "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/application/ports/repositories"
    click PortsSecurity "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/application/ports/security"
    click PortsValidation "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/application/ports/validation"
    click UseCases "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/application/use-cases"
    click AppErrors "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/application/errors"
    click ValidationComp "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/application/validation"
    click Controllers "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/presentation/controllers"
    click Middlewares "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/presentation/middlewares/authentication"
    click Responses "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/presentation/responses"
    click ExpressServer "https://github.com/xalsie/clean-architecture-api-boilerplate/blob/main/src/infrastructure/express/server.ts"
    click ExpressRoutes "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/express/routes"
    click ExpressAdapters "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/express/adapters"
    click ExpressMiddlewares "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/express/middlewares"
    click ExpressSetup "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/express/setup"
    click Knex "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/knex"
    click SQLTokenRepo "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/repositories/token/sql"
    click SQLUserRepo "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/infrastructure/repositories/user/sql"
    click DefaultRepo "https://github.com/xalsie/clean-architecture-api-boilerplate/blob/main/src/infrastructure/repositories/*-default-repository.ts"
    click Sanitizers "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/common/adapters/sanitizers"
    click SecurityAdapters "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/common/adapters/security"
    click Validators "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/common/adapters/validators"
    click Helpers "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/common/helpers"
    click ControllerFactories "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/main/factories/controllers"
    click MiddlewareFactories "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/main/factories/middlewares/authentication"
    click AppWiring "https://github.com/xalsie/clean-architecture-api-boilerplate/tree/main/src/main"

    classDef domain fill:#fcf8d0,stroke:#e2c822
    classDef application fill:#d0ebff,stroke:#339af0
    classDef presentation fill:#e6ffed,stroke:#51cf66
    classDef infrastructure fill:#f1f3f5,stroke:#868e96
    classDef common fill:#fff0f6,stroke:#f06595
    classDef main fill:#e3fafc,stroke:#22b8cf
    classDef external fill:#fff7e6,stroke:#fcc419,stroke-dasharray: 5 5
```
