# khaikenly/domain-driven-hexagon-research architecture

> Architecture diagram of the GitHub repository khaikenly/domain-driven-hexagon-research, 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/khaikenly/domain-driven-hexagon-research
- Repository: https://github.com/khaikenly/domain-driven-hexagon-research

## Overview

##### Main Components
- Application Interface / User-Facing Layer – includes HTTP controllers, CLI controllers, GraphQL resolvers (see files like create-user.http.controller.ts, create-user.cli.controller.ts, and create-user.graphql-resolver.ts).
- Application/Core Layer – encompasses the use case implementations (commands/queries and their corresponding services), application-specific logic (transactional orchestration, command and query buses) and the “ports” (interfaces for repositories, loggers, etc.).
- Domain Layer – contains entities and aggregates (e.g., user.entity.ts and wallet.entity.ts), value objects (like address.value-object.ts), domain events (user-created.domain-event.ts, wallet-created.domain-event.ts), and domain error classes.
- Infrastructure Layer – includes actual implementations of external resources such as database access (the sql-repository.base.ts, user.repository.ts, wallet.repository.ts), configuration files, Docker integration, and deployment files.
- Shared / Utility Components – provided by libraries such as helper functions, custom decorators (like final.decorator.ts, frozen.decorator.ts), guard utilities, and exception handling.

##### Relationships and Interactions
- Data flows from the outermost adapter layer into the core application via controllers (or resolvers) which accept a DTO, then map the data into a Command/Query.
- The Command/Query is processed by application services. These interact with the domain layer (entities, aggregates, value objects) to perform business logic.
- All external interactions (such as database operations or logging) are done through dedicated “ports” — abstract interfaces defined in the core and implemented in the infrastructure.
- Domain events may be dispatched from services or entities and then handled by appropriate event handlers (for example, to create a wallet when a user is created).
- Finally, after processing, data is converted into Response DTOs which are sent back to the clients.

##### Architectural Patterns
- Domain-Driven Design (DDD): Emphasize entities, aggregates, value objects, domain events, and domain invariants.
- Separation of Concerns via Vertical Slicing of Modules: Note how each business domain (User, Wallet) is managed within its module. Inside modules, separate folders for commands (state-changing use cases) and queries (read models) keep related classes together.
- Clean/Onion Architecture: Show the inner core (domain) that remains independent of external concerns and ensure that dependencies point inward.

##### Technologies and Frameworks
- NodeJS and TypeScript as the chosen language/platform.
- NestJS as the web framework providing the controllers, dependency injection, and possibly the CQRS module.
- Slonik for type-safe SQL database interactions.
- Test frameworks related to Jest (see jest-e2e.json and tests directory) and possibly a tool like Dependency Cruiser (with the .dependency-cruiser.js file) to enforce architectural boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Interface / User-Facing Layer
    subgraph "Application Interface (Controllers/Resolvers)"
        A1["create-user.http.controller"]:::controller
        A2["create-user.cli.controller"]:::controller
        A3["create-user.graphql-resolver"]:::controller
    end

    %% Application/Core Layer
    subgraph "Application/Core Layer"
        B1["create-user.command"]:::service
        B2["create-user.service"]:::service
        B3["find-users.query-handler"]:::service
        B4["AppRequestContext"]:::service
        B5["exception.interceptor"]:::service
    end

    %% Domain Layer
    subgraph "Domain Layer"
        C1["user.entity"]:::domain
        C2["wallet.entity"]:::domain
        C3["user-created.domain-event"]:::domainevent
        C4["user-deleted.domain-event"]:::domainevent
        C5["user-address-updated.domain-event"]:::domainevent
        C6["user-role-changed.domain-event"]:::domainevent
        C7["wallet-created.domain-event"]:::domainevent
        C8["address.value-object"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        D1["user.repository"]:::infrastructure
        D2["wallet.repository"]:::infrastructure
        D3["sql-repository.base"]:::infrastructure
        D4["database.config"]:::infrastructure
        D5["database/migrations"]:::infrastructure
        D6["docker-compose.yml"]:::infrastructure
    end

    %% Shared / Utility Components
    subgraph "Shared / Utility Components"
        E1["final.decorator"]:::shared
        E2["frozen.decorator"]:::shared
        E3["exception.base"]:::shared
        E4["exceptions"]:::shared
        E5["Utils & Helpers"]:::shared
        E6["repository.port"]:::shared
        E7["logger.port"]:::shared
    end

    %% Data Flow Connections
    %% From Application Interface to Application/Core Layer
    A1 -->|"DTOs"| B1
    A2 -->|"DTOs"| B1
    A3 -->|"DTOs"| B1

    %% Within Application/Core Layer
    B1 -->|"Command Conversion"| B2
    B2 -->|"Query Bus"| B3
    B2 -->|"Context Passing"| B4
    B2 -->|"Exception Handling"| B5

    %% Application/Core to Domain Layer (Business Logic)
    B2 -->|"Executes"| C1
    B2 -->|"Executes"| C2

    %% Domain Layer Domain Events
    C1 -->|"Emits"| C3
    C1 -->|"Emits"| C4
    C1 -->|"Emits"| C5
    C1 -->|"Emits"| C6
    C2 -->|"Emits"| C7

    %% Domain Layer Value Object association
    C1 ---|"Uses"| C8

    %% Application/Core calls Ports (Shared Interfaces)
    B2 -->|"Calls Port"| E6
    B2 -->|"Logs Through"| E7

    %% Ports to Infrastructure (Repository Implementations)
    E6 -->|"Implements"| D1
    E6 -->|"Implements"| D2
    D1 -->|"Base Mapper"| D3
    D2 -->|"Base Mapper"| D3

    %% Infrastructure uses Database Configurations/Migrations
    D1 -->|"Uses"| D4
    D2 -->|"Uses"| D4
    D4 -->|"Managed via"| D5

    %% Infrastructure Containerization
    D5 -->|"Deploys With"| D6

    %% Response flow from Core back to Interface (not explicitly drawn)
    B2 ---|"Response DTO"| A1
    B2 ---|"Response DTO"| A2
    B2 ---|"Response DTO"| A3

    %% Click Events for Application Interface / User-Facing Layer
    click A1 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/commands/create-user/create-user.http.controller.ts"
    click A2 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/commands/create-user/create-user.cli.controller.ts"
    click A3 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/commands/create-user/graphql-example/create-user.graphql-resolver.ts"

    %% Click Events for Application/Core Layer
    click B1 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/commands/create-user/create-user.command.ts"
    click B2 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/commands/create-user/create-user.service.ts"
    click B3 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/queries/find-users/find-users.query-handler.ts"
    click B4 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/application/context/AppRequestContext.ts"
    click B5 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/application/interceptors/exception.interceptor.ts"

    %% Click Events for Domain Layer
    click C1 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/domain/user.entity.ts"
    click C2 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/wallet/domain/wallet.entity.ts"
    click C3 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/domain/events/user-created.domain-event.ts"
    click C4 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/domain/events/user-deleted.domain-event.ts"
    click C5 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/domain/events/user-address-updated.domain-event.ts"
    click C6 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/domain/events/user-role-changed.domain-event.ts"
    click C7 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/wallet/domain/events/wallet-created.domain-event.ts"
    click C8 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/domain/value-objects/address.value-object.ts"

    %% Click Events for Infrastructure Layer
    click D1 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/user/database/user.repository.ts"
    click D2 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/modules/wallet/database/wallet.repository.ts"
    click D3 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/db/sql-repository.base.ts"
    click D4 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/configs/database.config.ts"
    click D5 "https://github.com/khaikenly/domain-driven-hexagon-research/tree/master/database/migrations"
    click D6 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/docker/docker-compose.yml"

    %% Click Events for Shared / Utility Components
    click E1 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/decorators/final.decorator.ts"
    click E2 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/decorators/frozen.decorator.ts"
    click E3 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/exceptions/exception.base.ts"
    click E4 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/exceptions/exceptions.ts"
    click E5 "https://github.com/khaikenly/domain-driven-hexagon-research/tree/master/src/libs/utils"
    click E6 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/ddd/repository.port.ts"
    click E7 "https://github.com/khaikenly/domain-driven-hexagon-research/blob/master/src/libs/ports/logger.port.ts"

    %% Class Definitions for Styling
    classDef controller fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef service fill:#d4edda,stroke:#155724,stroke-width:2px,stroke-dasharray: 5 5;
    classDef domain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef domainevent fill:#f8d7da,stroke:#721c24,stroke-width:2px,stroke-dasharray: 2 2;
    classDef infrastructure fill:#fefefe,stroke:#6c757d,stroke-width:2px,stroke-dasharray: 4 2;
    classDef shared fill:#e2e3e5,stroke:#383d41,stroke-width:2px;
```
