# alexandrebulete/ddd-foundation architecture

> Architecture diagram of the GitHub repository alexandrebulete/ddd-foundation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexandrebulete/ddd-foundation
- Repository: https://github.com/alexandrebulete/ddd-foundation

## Overview

DDD Foundation is a pure PHP library of reusable domain and application building blocks, not a standalone service. A project defines commands/queries and handlers; query handlers configure repository operations, while domain value objects, events, criteria, and repository contracts support that work. The included in-memory repository provides a test-double implementation with filtering, sorting, and pagination. README capabilities such as authorization, activity journaling, and selectable enums are represented as documented branches; their runtime connections are not shown in the excerpts.

Main entry points: [`src/Domain/Repository/RepositoryInterface.php`](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/RepositoryInterface.php) (Repository contract), [`src/Application/Query/QueryInterface.php`](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/QueryInterface.php) (Query contracts), [`src/Application/Handler/QueryCollectionHandler.php`](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Handler/QueryCollectionHandler.php) (Collection handler), [`src/Application/Handler/QuerySingleHandler.php`](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Handler/QuerySingleHandler.php) (Single handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_command_contracts["Command contracts"]
  node_command_handler["Command handlers"]
  node_command_bus["Command bus"]
  node_query_contracts["Query contracts<br/>[QueryInterface.php]"]
  node_query_handler_markers["Query handler markers<br/>[AsQueryHandler.php]"]
  node_query_bus["Query bus"]
  node_collection_handler["Collection handler"]
  node_single_handler["Single handler"]
  node_criteria_builder["Criteria builder"]
  node_criteria_normalizer["Criteria normalizer"]
  node_authorization["Authorization<br/>[Permission.php]"]
  node_activity["Activity journaling"]
  node_event_dispatch["Event dispatcher contract"]
end

subgraph group_domain["Domain"]
  node_domain_events["Domain events<br/>[DomainEvent.php]"]
  node_event_recording["Event recording<br/>[RecordsEvents.php]"]
  node_repository_contract["Repository contract"]
  node_comparison["Comparison vocabulary<br/>[Comparison.php]"]
  node_paginator_contract["Paginator contract"]
  node_entity_not_found["Not-found exception"]
  node_value_objects["Value objects<br/>[IdentifierVO.php]"]
  node_selectable_enum["Selectable enums"]
end

subgraph group_inmemory["In-memory infrastructure"]
  node_inmemory_repository[("In-memory repository")]
  node_inmemory_paginator["In-memory paginator"]
end

node_project(("DDD project"))

node_project -.->|"defines commands"| node_command_contracts
node_project -.->|"implements handlers"| node_command_handler
node_project -.->|"defines queries"| node_query_contracts
node_project -.->|"marks handlers"| node_query_handler_markers
node_project -->|"builds criteria"| node_criteria_builder
node_project -.->|"uses permissions"| node_authorization
node_project -.->|"journals activity"| node_activity
node_project -.->|"dispatches events"| node_event_dispatch
node_project -->|"selects enum choices"| node_selectable_enum
node_command_handler -.->|"handles"| node_command_contracts
node_command_bus -->|"dispatches"| node_command_contracts
node_query_bus -->|"asks"| node_query_contracts
node_collection_handler -->|"reads query"| node_query_contracts
node_single_handler -->|"reads query"| node_query_contracts
node_collection_handler -->|"normalizes criteria"| node_criteria_normalizer
node_collection_handler -->|"configures repository"| node_repository_contract
node_single_handler -->|"finds entity"| node_repository_contract
node_single_handler -->|"throws when absent"| node_entity_not_found
node_criteria_builder -->|"uses vocabulary"| node_comparison
node_criteria_normalizer -->|"uses vocabulary"| node_comparison
node_event_recording -->|"records events"| node_domain_events
node_event_dispatch -->|"dispatches"| node_domain_events
node_repository_contract -->|"returns paginator"| node_paginator_contract
node_repository_contract -->|"looks up identifier"| node_value_objects
node_inmemory_repository -->|"implements"| node_repository_contract
node_inmemory_repository -->|"parses filters"| node_comparison
node_inmemory_repository -->|"creates paginator"| node_inmemory_paginator
node_inmemory_paginator -->|"implements"| node_paginator_contract

click node_command_contracts "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Command/CommandInterface.php"
click node_command_handler "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Command/AsCommandHandler.php"
click node_command_bus "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Command/CommandBusInterface.php"
click node_query_contracts "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/QueryInterface.php"
click node_query_handler_markers "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/AsQueryHandler.php"
click node_query_bus "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/QueryBusInterface.php"
click node_collection_handler "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Handler/QueryCollectionHandler.php"
click node_single_handler "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Handler/QuerySingleHandler.php"
click node_criteria_builder "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Criteria/CriteriaBuilder.php"
click node_criteria_normalizer "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Criteria/CriteriaNormalizer.php"
click node_authorization "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Authorization/Permission.php"
click node_activity "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Activity/ActivityDescription.php"
click node_event_dispatch "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Event/EventDispatcherInterface.php"
click node_domain_events "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Event/DomainEvent.php"
click node_event_recording "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Model/RecordsEvents.php"
click node_repository_contract "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/RepositoryInterface.php"
click node_comparison "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/Comparison.php"
click node_paginator_contract "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/PaginatorInterface.php"
click node_entity_not_found "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Exception/EntityNotFoundException.php"
click node_value_objects "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/ValueObject/IdentifierVO.php"
click node_selectable_enum "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Trait/AsSelectableEnum.php"
click node_inmemory_repository "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Infrastructure/InMemory/InMemoryRepository.php"
click node_inmemory_paginator "https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Infrastructure/InMemory/InMemoryPaginator.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command_contracts,node_command_handler,node_command_bus,node_query_contracts,node_query_handler_markers,node_query_bus,node_collection_handler,node_single_handler,node_criteria_builder,node_criteria_normalizer,node_authorization,node_activity,node_event_dispatch toneBlue
class node_domain_events,node_event_recording,node_repository_contract,node_comparison,node_paginator_contract,node_entity_not_found,node_value_objects,node_selectable_enum toneAmber
class node_inmemory_repository,node_inmemory_paginator toneMint
class node_project toneIndigo
```

## Components

### Application

- [Command contracts](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Command/CommandInterface.php): `src/Application/Command/CommandInterface.php`
- [Command handlers](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Command/AsCommandHandler.php): `src/Application/Command/AsCommandHandler.php`
- [Command bus](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Command/CommandBusInterface.php): `src/Application/Command/CommandBusInterface.php`
- [Query contracts](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/QueryInterface.php): `src/Application/Query/QueryInterface.php`
- [Query handler markers](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/AsQueryHandler.php): `src/Application/Query/AsQueryHandler.php`
- [Query bus](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Query/QueryBusInterface.php): `src/Application/Query/QueryBusInterface.php`
- [Collection handler](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Handler/QueryCollectionHandler.php): `src/Application/Handler/QueryCollectionHandler.php`
- [Single handler](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Handler/QuerySingleHandler.php): `src/Application/Handler/QuerySingleHandler.php`
- [Criteria builder](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Criteria/CriteriaBuilder.php): `src/Application/Criteria/CriteriaBuilder.php`
- [Criteria normalizer](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Criteria/CriteriaNormalizer.php): `src/Application/Criteria/CriteriaNormalizer.php`
- [Authorization](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Authorization/Permission.php): `src/Application/Authorization/Permission.php`
- [Activity journaling](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Activity/ActivityDescription.php): `src/Application/Activity/ActivityDescription.php`
- [Event dispatcher contract](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Application/Event/EventDispatcherInterface.php): `src/Application/Event/EventDispatcherInterface.php`

### Domain

- [Domain events](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Event/DomainEvent.php): `src/Domain/Event/DomainEvent.php`
- [Event recording](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Model/RecordsEvents.php): `src/Domain/Model/RecordsEvents.php`
- [Repository contract](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/RepositoryInterface.php): `src/Domain/Repository/RepositoryInterface.php`
- [Comparison vocabulary](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/Comparison.php): `src/Domain/Repository/Comparison.php`
- [Paginator contract](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Repository/PaginatorInterface.php): `src/Domain/Repository/PaginatorInterface.php`
- [Not-found exception](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Exception/EntityNotFoundException.php): `src/Domain/Exception/EntityNotFoundException.php`
- [Value objects](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/ValueObject/IdentifierVO.php): `src/Domain/ValueObject/IdentifierVO.php`
- [Selectable enums](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Domain/Trait/AsSelectableEnum.php): `src/Domain/Trait/AsSelectableEnum.php`

### In-memory infrastructure

- [In-memory repository](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Infrastructure/InMemory/InMemoryRepository.php): `src/Infrastructure/InMemory/InMemoryRepository.php`
- [In-memory paginator](https://github.com/alexandrebulete/ddd-foundation/blob/main/src/Infrastructure/InMemory/InMemoryPaginator.php): `src/Infrastructure/InMemory/InMemoryPaginator.php`

### Other components

- **DDD project**

## Connections

- DDD project → Command contracts: defines commands (evidence: `README.md`)
- DDD project → Command handlers: implements handlers (evidence: `README.md`)
- DDD project → Query contracts: defines queries (evidence: `README.md`)
- DDD project → Query handler markers: marks handlers (evidence: `README.md`)
- DDD project → Criteria builder: builds criteria (evidence: `README.md`)
- DDD project → Authorization: uses permissions (evidence: `README.md`)
- DDD project → Activity journaling: journals activity (evidence: `README.md`)
- DDD project → Event dispatcher contract: dispatches events (evidence: `src/Application/Event/EventDispatcherInterface.php`)
- DDD project → Selectable enums: selects enum choices (evidence: `README.md`)
- Command handlers → Command contracts: handles (evidence: `README.md`)
- Command bus → Command contracts: dispatches (evidence: `src/Application/Command/CommandBusInterface.php`)
- Query bus → Query contracts: asks (evidence: `src/Application/Query/QueryBusInterface.php`)
- Collection handler → Query contracts: reads query (evidence: `src/Application/Handler/QueryCollectionHandler.php`)
- Single handler → Query contracts: reads query (evidence: `src/Application/Handler/QuerySingleHandler.php`)
- Collection handler → Criteria normalizer: normalizes criteria (evidence: `src/Application/Handler/QueryCollectionHandler.php`)
- Collection handler → Repository contract: configures repository (evidence: `src/Application/Handler/QueryCollectionHandler.php`)
- Single handler → Repository contract: finds entity (evidence: `src/Application/Handler/QuerySingleHandler.php`)
- Single handler → Not-found exception: throws when absent (evidence: `src/Application/Handler/QuerySingleHandler.php`)
- Criteria builder → Comparison vocabulary: uses vocabulary (evidence: `src/Application/Criteria/CriteriaBuilder.php`)
- Criteria normalizer → Comparison vocabulary: uses vocabulary (evidence: `src/Application/Criteria/CriteriaNormalizer.php`)
- Event recording → Domain events: records events (evidence: `src/Domain/Model/RecordsEvents.php`)
- Event dispatcher contract → Domain events: dispatches (evidence: `src/Application/Event/EventDispatcherInterface.php`)
- Repository contract → Paginator contract: returns paginator (evidence: `src/Domain/Repository/RepositoryInterface.php`)
- Repository contract → Value objects: looks up identifier (evidence: `src/Domain/Repository/RepositoryInterface.php`)
- In-memory repository → Repository contract: implements (evidence: `src/Infrastructure/InMemory/InMemoryRepository.php`)
- In-memory repository → Comparison vocabulary: parses filters (evidence: `src/Infrastructure/InMemory/InMemoryRepository.php`)
- In-memory repository → In-memory paginator: creates paginator (evidence: `src/Infrastructure/InMemory/InMemoryRepository.php`)
- In-memory paginator → Paginator contract: implements (evidence: `src/Infrastructure/InMemory/InMemoryPaginator.php`)
