# sairyss/domain-driven-hexagon architecture

> Architecture diagram of the GitHub repository sairyss/domain-driven-hexagon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sairyss/domain-driven-hexagon
- Repository: https://github.com/sairyss/domain-driven-hexagon

## Overview

##### Main architectural layers and components
- Interface Adapters (Presentation Layer): Include HTTP Controllers, CLI Controllers, GraphQL Resolvers, and DTOs as the user-facing gateways (found in “src/modules/...controllers” and “src/modules/...dtos”) that translate incoming request DTOs into Commands/Queries, then receive responses.
- Infrastructure Layer: Represented by the “database” (migrations, seeds, and migration tools), “docker” configuration files, and repository implementations (in “src/libs/db” and “src/modules/*/database”). Emphasize adapters that implement the ports for persistence (using Slonik for SQL) and other external resources.

##### Relationships and data flows between components
- How domain events (e.g., “user-created” events) trigger further actions (like wallet creation) via event handlers in the application layer.
- Dependency inversion where the core business logic never directly depends on external frameworks; only ports (interfaces) are defined in the core, and external adapters (infrastructure layer) implement them.

##### Architectural patterns and design principles used
- Hexagonal (Ports and Adapters) Architecture: Illustrate the separation between the core domain and external concerns (interfaces vs. adapters) with clearly labeled ports.
- Command–Query Separation (CQS/CQRS): Indicate the separate pathways for commands (state-changing operations) and queries (data retrieval operations) in the application layer.

##### Technologies and libraries in your labels
- Mention that the project is built using NodeJS, TypeScript, and the NestJS framework.
- Use of Slonik for database access.
- Testing approaches (e.g., e2e tests, behavioral testing with Gherkin) and other supportive tools (e.g., dependency cruiser for validating dependencies).

##### Important details to capture
- The modular design (vertical slicing): Each module (like “user” and “wallet”) has its own well-defined components (commands, queries, domain logic, controllers, DTOs) encapsulated within its own folder.
- The separation of concerns with distinct configuration files (environment variables, Docker Compose, testing setups) and how these support deployment and testing without interfering with the core business logic.
- The overall layered architecture from external clients (HTTP/GraphQL/CLI) to core domain (business rules) to the infrastructure level (database interactions and external service communications).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::external

    %% Interface Adapters
    subgraph "Interface Adapters"
        HTTPCreate["HTTP Controller (CreateUser)"]:::interface
        HTTPFind["HTTP Controller (FindUsers)"]:::interface
        CLI["CLI Controller (CreateUser)"]:::interface
        GQLCreate["GraphQL Resolver (CreateUser)"]:::interface
        GQLFind["GraphQL Resolver (FindUsers)"]:::interface
        DTO["User DTOs"]:::interface
    end

    %% Application Layer
    subgraph "Application Layer"
        CmdCreate["User Command Handler (CreateUser)"]:::application
        CmdDelete["User Command Handler (DeleteUser)"]:::application
        QueryFind["User Query Handler (FindUsers)"]:::application
        Bus["NestJS CQRS Bus"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        UserDomain["User Domain"]:::domain
        WalletCore["Wallet Domain"]:::domain
        WalletEvent["Wallet Event Handler"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        UserRepo["User Repository"]:::infra
        WalletRepo["Wallet Repository"]:::infra
        SQLRepoBase["SQL Repository Base"]:::infra
        DBMigrations["Database Migrations & Seeds"]:::infra
        DBConfig["Database Config"]:::infra
    end

    %% External Client to Interface Adapters
    Client --> HTTPCreate
    Client --> HTTPFind
    Client --> CLI
    Client --> GQLCreate
    Client --> GQLFind
    Client --> DTO

    %% Interface Adapters to Application Layer
    HTTPCreate -->|"calls"| CmdCreate
    CLI -->|"calls"| CmdCreate
    GQLCreate -->|"calls"| CmdCreate
    HTTPFind -->|"calls"| QueryFind
    GQLFind -->|"calls"| QueryFind

    %% Application Layer internal flow
    CmdCreate -->|"dispatches"| Bus
    CmdDelete -->|"dispatches"| Bus
    QueryFind -->|"dispatches"| Bus

    %% Application Layer to Domain Layer
    Bus -->|"invokes"| UserDomain

    %% Domain Layer interactions
    UserDomain -->|"triggers"| WalletEvent
    UserDomain -->|"persists"| UserRepo
    WalletEvent -->|"handles wallet creation"| WalletRepo
    WalletCore ---|"encapsulates wallet logic"| WalletEvent

    %% Infrastructure Layer Dependencies
    UserRepo -->|"uses"| SQLRepoBase
    WalletRepo -->|"uses"| SQLRepoBase
    DBConfig -->|"configures"| SQLRepoBase
    DBMigrations -->|"sets up"| SQLRepoBase

    %% Click Events for Interface Adapters
    click HTTPCreate "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/user/commands/create-user/create-user.http.controller.ts"
    click HTTPFind "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/user/queries/find-users/find-users.http.controller.ts"
    click CLI "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/user/commands/create-user/create-user.cli.controller.ts"
    click GQLCreate "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/user/commands/create-user/graphql-example/create-user.graphql-resolver.ts"
    click GQLFind "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/user/queries/find-users/find-users.graphql-resolver.ts"
    click DTO "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/user/dtos"

    %% Click Events for Application Layer
    click CmdCreate "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/user/commands/create-user"
    click CmdDelete "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/user/commands/delete-user"
    click QueryFind "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/user/queries/find-users"

    %% Click Events for Domain Layer
    click UserDomain "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/user/domain"
    click WalletCore "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/wallet/domain"
    click WalletEvent "https://github.com/sairyss/domain-driven-hexagon/tree/master/src/modules/wallet/application/event-handlers"

    %% Click Events for Infrastructure Layer
    click UserRepo "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/user/database/user.repository.ts"
    click WalletRepo "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/modules/wallet/database/wallet.repository.ts"
    click SQLRepoBase "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/libs/db/sql-repository.base.ts"
    click DBMigrations "https://github.com/sairyss/domain-driven-hexagon/tree/master/database/migrations"
    click DBConfig "https://github.com/sairyss/domain-driven-hexagon/blob/master/src/configs/database.config.ts"

    %% Styles
    classDef external fill:#E0BBE4,stroke:#5D3A9B,stroke-width:2px;
    classDef interface fill:#FFDFBA,stroke:#FF9F1C,stroke-width:2px;
    classDef application fill:#BAE1FF,stroke:#0F4C81,stroke-width:2px;
    classDef domain fill:#C3FDB8,stroke:#2B7129,stroke-width:2px;
    classDef infra fill:#F3E5AB,stroke:#B88A00,stroke-width:2px;
```
