# itlibrium/ddd-starter-dotnet architecture

> Architecture diagram of the GitHub repository itlibrium/ddd-starter-dotnet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itlibrium/ddd-starter-dotnet
- Repository: https://github.com/itlibrium/ddd-starter-dotnet

## Overview

##### Project type and purpose
- This is a modular monolith / sample framework project (“DDD-starter-dotnet”) demonstrating Domain-Driven Design (DDD) patterns, hexagonal architecture, CQRS, event sourcing, outbox, BDD, etc., in C#/.NET.
- It provides multiple “bounded contexts” (Contacts, Sales, Payments, ProductsDelivery, RiskManagement, Search, TechnicalStuff) each implemented in its own set of projects (DeepModel, ProcessModel, Adapters.Api, Adapters.Out, FluentMigrations, IntegrationTests, etc.). A separate Startup project composes everything, and a Build folder contains Nuke-based CI/CD automation and Docker-Compose definitions for infrastructure.

##### File structure
- Top-level directories:
- Build/Nuke·… → build scripts and Docker-Compose tasks for spinning up Postgres, Elasticsearch, Kafka, etc.
- Sources/… → each bounded context under its own folder, following “screaming architecture” (folder and namespace names reveal business domain and layers).
- Each context typically has layers:
– *.DeepModel (domain layer, hexagon’s core)
– *.ProcessModel (application / use-case layer)
– *.Adapters.Api (incoming port, REST controllers)
– *.Adapters.Out (outgoing port, repositories, external integrations)
– *.Crud or simple single-layer projects (in Contacts) for straight CRUD.
– *.Tests or IntegrationTests (testing).
- Sources/Monolith.Startup and Sources/Search.Startup → host entire system or Search module, wire up DI, configuration, middleware.
- TechnicalStuff → reusable cross-cutting libraries (persistence abstractions, outbox, Kafka, JSON converters, transactions, etc.).

##### Extract architecture hints from the README
- “Screaming architecture”: bounded contexts mapped to solution folders; hexagonal only for high-complexity DeepModel in Sales; simple CRUD for Contacts.
- Demonstrates DDD building blocks (Aggregates, Value Objects, Policies, Factories, Domain Services) in DeepModel.
- Uses Outbox Pattern and event publishing (TransactionalOutbox, NonTransactionalOutbox).
- Startup code in separate project.

A. Build / Infrastructure orchestration
- Nuke build orchestrator
- Docker-Compose (Postgres, Elasticsearch, Kafka)
For each module (e.g. Sales):
– Incoming Port: Adapters.Api (REST controllers)
– Application Layer: ProcessModel (use-case handlers, outbox ports)
– Domain Layer: DeepModel (aggregates, value objects, policies)
– Outgoing Ports & Adapters: Adapters.Out (SQL/EF/raw/document repositories, external service clients for Payments, RiskManagement, ProductsDelivery or in-memory fakes)
– Integration with TechnicalStuff libs (Persistence, Outbox, Transactions, Kafka)
For simple CRUD contexts (Contacts): single-layer CRUD project + EF DAO + REST controllers.
C. Shared Startup host(s)
- Monolith.Startup (aggregate of all BCs)
- Search.Startup (for the Search module only)
D. Infrastructure services
- Postgres DB(s) for main contexts
- Elasticsearch for Search context
- Kafka cluster for event-driven integrations
E. Cross‐cutting libraries (TechnicalStuff)

##### Relationships and data flows
- Client HTTP → Adapters.Api → ProcessModel handlers → Domain DeepModel → Adapters.Out writes to DB / emits events to Outbox → outbox processor sends to Kafka → Kafka topics consumed by other BC adapters.
- ProcessModel may read CRUD tables (Contacts or Sales CRUD tables) in same transaction.
- Adapters.Out for external services: HTTP calls or in-memory.
- Startup wires up: configuration → DI container → module registrations → middleware pipelines → outbox background services.

##### Architectural patterns and design principles
- Hexagonal Architecture in Sales.DeepModel / Sales.ProcessModel / Sales.Adapters.*
- Single-layer CRUD in Contacts (anemic, directly using EF).
- DDD building blocks in domain layer (Aggregates, Value Objects, Domain Events, Policies, Factories, Domain Services).
- Outbox pattern for reliable event publishing (Transactional vs Non-Transactional).
- Screaming architecture: project names, namespaces and folder structure map directly to BCs and layers.
- Separate Startup host for composition root.
- Use of cross-cutting abstractions (TechnicalStuff) so adapters and use-cases remain technology-agnostic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build & Infra Orchestration"
        NUKE["Nuke Build Orchestrator"]:::build
        DOCKER["Docker-Compose"]:::build
    end
    click NUKE "https://github.com/itlibrium/ddd-starter-dotnet/tree/master/Build/Nuke"
    click DOCKER "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Build/Nuke.DockerCompose"

    subgraph "Monolith Startup Host"
        MONO["Monolith.Startup"]:::startup
    end
    click MONO "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Monolith.Startup"

    Client["HTTP Client"]:::external

    subgraph "Bounded Contexts"
        subgraph Contacts
            C_API["Contacts (CRUD API)"]:::api
        end
        click C_API "https://github.com/itlibrium/ddd-starter-dotnet/tree/master/Sources/Contacts/Contacts"

        subgraph Sales
            S_API["Sales API"]:::api
            S_APP["Sales ProcessModel"]:::app
            S_DOMAIN["Sales DeepModel"]:::domain
            S_OUT["Sales Adapters.Out"]:::infra
            S_MIG["Sales Migrations"]:::infra
            S_TEST["Sales IntegrationTests"]:::infra
            S_API --> S_APP --> S_DOMAIN --> S_OUT --> S_MIG
        end
        click S_API "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Sales/Sales.RestApi"
        click S_APP "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Sales/Sales.ProcessModel"
        click S_DOMAIN "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Sales/Sales.DeepModel"
        click S_OUT "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Sales/Sales.Adapters"
        click S_MIG "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Sales/Sales.FluentMigrations"
        click S_TEST "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Sales/Sales.IntegrationTests"

        subgraph Payments
            P_API["Payments API"]:::api
            P_APP["Payments ProcessModel"]:::app
            P_DOMAIN["Payments DeepModel"]:::domain
            P_OUT["Payments Adapters.Out"]:::infra
            P_API --> P_APP --> P_DOMAIN --> P_OUT
        end
        click P_API "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Payments/Payments.Adapters.Api"
        click P_APP "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Payments/Payments.ProcessModel"
        click P_DOMAIN "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Payments/Payments.DeepModel"
        click P_OUT "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Payments/Payments.Adapters.Out"

        subgraph ProductsDelivery
            PD_API["ProductsDelivery API"]:::api
            PD_APP["ProductsDelivery ProcessModel"]:::app
            PD_DOMAIN["ProductsDelivery DeepModel"]:::domain
            PD_OUT["ProductsDelivery Adapters.Out"]:::infra
            PD_API --> PD_APP --> PD_DOMAIN --> PD_OUT
        end
        click PD_API "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/ProductsDelivery/ProductsDelivery.Adapters.Api"
        click PD_APP "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/ProductsDelivery/ProductsDelivery.ProcessModel"
        click PD_DOMAIN "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/ProductsDelivery/ProductsDelivery.DeepModel"
        click PD_OUT "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/ProductsDelivery/ProductsDelivery.Adapters.Out"

        subgraph RiskManagement
            RM_API["RiskManagement API"]:::api
            RM_APP["RiskManagement ProcessModel"]:::app
            RM_DOMAIN["RiskManagement DeepModel"]:::domain
            RM_OUT["RiskManagement Adapters.Out"]:::infra
            RM_API --> RM_APP --> RM_DOMAIN --> RM_OUT
        end
        click RM_API "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/RiskManagement/RiskManagement.Adapters.Api"
        click RM_APP "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/RiskManagement/RiskManagement.ProcessModel"
        click RM_DOMAIN "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/RiskManagement/RiskManagement.DeepModel"
        click RM_OUT "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/RiskManagement/RiskManagement.Adapters.Out"

        subgraph Search
            SS_API["Search API"]:::api
            SS_INF["Search Infrastructure"]:::infra
            SS_API --> SS_INF
        end
        click SS_API "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Search/Search.Api"
        click SS_INF "https://github.com/itlibrium/ddd-starter-dotnet/blob/master/Sources/Search/Search.Infrastructure"
    end

    subgraph "Infrastructure Services"
        PG["Postgres"]:::infra_services
        ES["Elasticsearch"]:::infra_services
        KAFKA["Kafka Cluster"]:::infra_services
    end

    Client --> C_API --> PG
    Client --> S_API
    S_OUT --> PG
    SS_INF --> ES
    S_OUT -->|"Outbox"| KAFKA
    KAFKA -->|"Consumed by Adapters.Out"| P_OUT
    KAFKA --> RM_OUT
    Client --> SS_API

    classDef domain fill:#ADD8E6,stroke:#000;
    classDef app fill:#90EE90,stroke:#000;
    classDef infra fill:#FFA500,stroke:#000;
    classDef api fill:#DDA0DD,stroke:#000;
    classDef startup fill:#C0C0C0,stroke:#000;
    classDef build fill:#EEEEEE,stroke:#000;
    classDef infra_services fill:#FF6347,stroke:#000;
    classDef external fill:#FFFFFF,stroke:#000;
```
