Referência de Domain-Driven Design em Python, do modelo à produção.
Bounded contexts, agregados, eventos de domínio, Unit of Work, concorrência otimista e uma arquitetura em camadas que o próprio CI impede de degradar.
- Por que este repositório existe
- O domínio
- Arquitetura
- Padrões DDD e onde encontrá-los
- Começando
- Usando a API
- Estrutura do projeto
- Qualidade
- Adicionando um bounded context
- Decisões de arquitetura
- Referências
A maioria dos exemplos de DDD mostra classes Entity e ValueObject e para por
aí. Os problemas difíceis ficam de fora: quando publicar um evento, como impedir
que duas requisições sobrescrevam a mesma tarefa, como dois contextos conversam
sem se acoplar, como garantir que ninguém importe o ORM dentro do domínio daqui a
seis meses.
Este projeto resolve esses pontos com código executável, testado e documentado:
- Domínio puro. Nenhuma importação de framework na camada de domínio, verificada a cada commit.
- Eventos publicados só depois do commit. Nada de reagir a uma mudança que depois sofreu rollback.
- Concorrência otimista. Escritas concorrentes resultam em
409 Conflict, nunca em lost update. - Dois bounded contexts reais integrados por eventos e por uma Anti-Corruption Layer.
- CQRS-lite. Commands passam pelo agregado; queries leem projeções.
- Problem Details (RFC 9457) para todo erro de domínio e de aplicação.
- 132 testes, ~98% de cobertura, rodando contra PostgreSQL no CI.
Gestão de tarefas com regras de negócio de verdade:
- uma tarefa encerrada (concluída ou cancelada) não pode mais ser alterada;
- o status muda apenas por transições permitidas;
- só tarefas com responsável podem ser iniciadas;
- cada responsável tem um limite de tarefas em andamento (WIP);
- o prazo não pode ser anterior à criação;
- ao receber uma tarefa, o responsável é notificado.
stateDiagram-v2
[*] --> pending: criar
pending --> in_progress: iniciar (exige responsável e respeita o WIP)
pending --> completed: concluir
pending --> cancelled: cancelar
in_progress --> completed: concluir
in_progress --> cancelled: cancelar
completed --> [*]
cancelled --> [*]
Os termos de negócio estão no glossário da Linguagem Ubíqua, e os contextos e suas relações no Context Map:
| Bounded context | Tipo | Responsabilidade |
|---|---|---|
| Task Management | Core Domain | Ciclo de vida das tarefas, prazos, limite de WIP |
| Notification | Generic Subdomain | Avisos às pessoas, independente da origem |
flowchart LR
TM["Task Management<br/>(Core)"] -- "TaskAssigned<br/>(Published Language)" --> ACL{{"Anti-Corruption Layer"}}
ACL -- "SendNotification" --> N["Notification<br/>(Generic)"]
A Layered Architecture de Eric Evans, com a regra de dependência apontando sempre para o domínio:
flowchart TB
I["<b>interfaces</b><br/>FastAPI · Typer"] --> B["<b>bootstrap</b><br/>Composition Root"]
B --> INF["<b>infrastructure</b><br/>SQLAlchemy · Alembic · Event Bus · ACL"]
INF --> APP["<b>application</b><br/>Commands · Queries · Unit of Work · Portas"]
APP --> D["<b>domain</b><br/>Agregados · Value Objects · Eventos · Domain Services"]
Cada camada é organizada por bounded context. As regras são verificadas pelo import-linter em cinco contratos: ordem das camadas, domínio e aplicação livres de frameworks, e independência entre contextos.
Como um comando atravessa o sistema:
sequenceDiagram
autonumber
participant API as Router (interfaces)
participant H as StartTaskHandler (application)
participant UoW as Unit of Work
participant P as WorkInProgressPolicy (domain)
participant T as Task (domain)
participant DB as PostgreSQL
participant Bus as Event Bus
API->>H: StartTask(task_id)
H->>UoW: abre transação
H->>UoW: tasks.get(id), tasks.list_by_assignee(...)
H->>P: start(task, tarefas_do_responsável)
P->>T: start()
T-->>T: valida e registra TaskStarted
H->>UoW: commit()
UoW->>DB: UPDATE ... WHERE version = n, depois COMMIT
UoW->>Bus: publica TaskStarted
Mais detalhes em docs/architecture.md.
| Padrão | Arquivo |
|---|---|
| Entity | domain/seedwork/entity.py |
| Aggregate Root | domain/seedwork/aggregate_root.py · Task |
| Value Object | domain/task_management/value_objects/ |
| Domain Event | domain/task_management/events/task_events.py |
| Domain Service | WorkInProgressPolicy |
| Specification | seedwork/specification.py · task_specifications.py |
| Factory | Task.create, Notification.create |
| Repository | contrato no domínio · implementação SQLAlchemy |
| Unit of Work | porta · implementação |
| Application Service | application/task_management/commands/ |
| Read Model (CQRS) | infrastructure/read_models/ |
| Anti-Corruption Layer | TaskEventsTranslator |
| Composition Root | bootstrap/container.py |
- Python 3.12+
- Poetry 2.x
- Docker (opcional, para PostgreSQL)
git clone https://github.com/LoboProgrammingg/DDD-Structure.git
cd DDD-Structure
cp .env.example .env
make install # dependências + hooks de pre-commit
make migrate # aplica as migrações
make run # http://localhost:8000/docsmake up # PostgreSQL + API; as migrações rodam na subida
make downTodos os comandos: make help.
A documentação interativa fica em /docs. Os endpoints são orientados a
comandos: cada verbo do negócio é uma ação explícita, mantendo a Linguagem
Ubíqua também no contrato HTTP.
| Método | Rota | Ação |
|---|---|---|
POST |
/api/v1/tasks |
Criar tarefa |
GET |
/api/v1/tasks?status=&assignee_id=&limit=&offset= |
Listar |
GET |
/api/v1/tasks/{id} |
Consultar |
POST |
/api/v1/tasks/{id}/rename |
Renomear |
POST |
/api/v1/tasks/{id}/reprioritize |
Repriorizar |
POST |
/api/v1/tasks/{id}/assign |
Atribuir responsável |
POST |
/api/v1/tasks/{id}/start |
Iniciar |
POST |
/api/v1/tasks/{id}/complete |
Concluir |
POST |
/api/v1/tasks/{id}/cancel |
Cancelar |
GET |
/health/live · /health/ready |
Liveness e readiness (com checagem do banco) |
# Criar
curl -s -X POST localhost:8000/api/v1/tasks \
-H 'Content-Type: application/json' \
-d '{"title": "Desenhar o context map", "priority": "high", "due_date": "2026-12-01"}'
# Atribuir (dispara TaskAssigned, e o contexto Notification avisa o responsável)
curl -s -X POST localhost:8000/api/v1/tasks/<id>/assign \
-H 'Content-Type: application/json' -d '{"assignee_id": "ana.souza"}'
# Iniciar e concluir
curl -s -X POST localhost:8000/api/v1/tasks/<id>/start
curl -s -X POST localhost:8000/api/v1/tasks/<id>/completeViolação de regra de negócio:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"detail": "A tarefa está 'completed' e não pode ser alterada.",
"code": "task_is_closed",
"instance": "/api/v1/tasks/3f1c.../rename"
}| Erro | HTTP |
|---|---|
Invariante violada (InvalidTaskTitle, InvalidTaskId...) |
422 |
Regra de negócio violada (TaskIsClosed, WorkInProgressLimitExceeded...) |
409 |
| Recurso inexistente | 404 |
| Escrita concorrente detectada | 409 |
Os mesmos casos de uso, por outro adaptador de entrada:
poetry run task-cli create "Revisar ADRs" --priority high
poetry run task-cli assign <id> ana.souza
poetry run task-cli start <id>
poetry run task-cli list --status in_progresssrc/app/
├── domain/ # Regras de negócio puras (só a biblioteca padrão)
│ ├── seedwork/ # Entity, AggregateRoot, ValueObject, DomainEvent, Specification
│ ├── task_management/ # Core Domain
│ │ ├── aggregates/ # Task (raiz do agregado)
│ │ ├── value_objects/ # TaskId, TaskTitle, TaskStatus, DueDate, AssigneeId...
│ │ ├── events/ # TaskCreated, TaskAssigned, TaskCompleted...
│ │ ├── exceptions/ # Erros tipados na Linguagem Ubíqua
│ │ ├── repositories/ # Contrato do repositório
│ │ ├── services/ # WorkInProgressPolicy
│ │ └── specifications/ # OpenTask, InProgressTask, OverdueTask, AssignedTo
│ └── notification/ # Generic Subdomain (mesma estrutura)
├── application/ # Casos de uso: orquestram, não decidem
│ ├── shared/ # UnitOfWork, EventPublisher, Clock, erros de aplicação
│ ├── task_management/
│ │ ├── commands/ # Um arquivo por caso de uso: command + handler
│ │ ├── queries/ # GetTask, ListTasks
│ │ ├── ports/ # TaskManagementUnitOfWork, TaskReadModel
│ │ └── dtos.py
│ └── notification/
├── infrastructure/ # Implementações das portas
│ ├── config/ # Pydantic Settings
│ ├── database/ # Engine, sessão, modelos ORM
│ ├── repositories/ # Repositórios SQLAlchemy (Identity Map + mapeamento explícito)
│ ├── unit_of_work.py # Transação, concorrência otimista, publicação pós-commit
│ ├── read_models/ # Consultas SQL que devolvem DTOs
│ ├── messaging/ # Event bus em processo
│ ├── notification/ # Canal de entrega e Anti-Corruption Layer
│ ├── providers/ # SystemClock
│ └── logging/ # Logs estruturados (JSON / console)
├── bootstrap/ # Composition Root
└── interfaces/ # Adaptadores de entrada
├── api/ # FastAPI: routers v1, schemas, Problem Details, request id
└── cli/ # Typer
tests/
├── unit/ # domínio e aplicação, sem I/O
├── integration/ # SQLAlchemy real: mapeamento, rollback, concorrência, fluxo entre contextos
└── e2e/ # contrato HTTP
docs/
├── architecture.md
├── context-map.md
├── ubiquitous-language.md
└── adr/ # Architecture Decision Records
migrations/ # Alembic
make check # lint + tipos + arquitetura + testes (o mesmo que o CI)| Verificação | Ferramenta | Onde roda |
|---|---|---|
| Lint e formatação | Ruff | pre-commit, CI |
| Tipos | mypy --strict (código e testes) |
pre-commit, CI |
| Arquitetura | import-linter (5 contratos) | pre-commit, CI |
| Testes | pytest + pytest-asyncio, cobertura mínima de 90% | CI, contra PostgreSQL 17 |
| Migrações | alembic upgrade, check e downgrade |
CI |
| Imagem | Docker multi-stage, usuário sem privilégios | CI |
| Commits | Conventional Commits | hook commit-msg |
Integração e e2e usam SQLite por padrão. Para rodar contra PostgreSQL:
docker compose up -d db
TEST_DATABASE_URL=postgresql+asyncpg://ddd:ddd@localhost:5432/ddd make test- Descreva os termos do novo contexto em
docs/ubiquitous-language.mde sua relação com os demais emdocs/context-map.md. - Crie o modelo em
src/app/domain/<contexto>/(agregados, value objects, eventos, exceções, contrato de repositório). Só biblioteca padrão. - Crie os casos de uso em
src/app/application/<contexto>/com a sua Unit of Work (ports/unit_of_work.py) e um arquivo por comando. - Implemente modelos ORM, repositório e Unit of Work em
src/app/infrastructure/e gere a migração commake migration m="...". - Integre com outros contextos por eventos. Se precisar consumir o modelo de outro contexto, traduza numa Anti-Corruption Layer na infraestrutura.
- Registre o wiring em
bootstrap/container.pye exponha eminterfaces/. - Adicione o contexto aos contratos
independencedo import-linter nopyproject.toml.
Cada escolha relevante tem um ADR com contexto, alternativas e consequências. Decisões revistas continuam no histórico, marcadas como substituídas.
| ADR | Decisão |
|---|---|
| 0001 | Arquitetura em camadas com regra de dependência |
| 0004 | Composition Root explícito, sem framework de DI |
| 0005 | Configuração centralizada com Pydantic Settings |
| 0006 | Contratos de repositório no domínio |
| 0007 | Unit of Work e publicação de eventos após o commit |
| 0008 | SQLAlchemy com mapeamento explícito e concorrência otimista |
| 0009 | Contratos de arquitetura com import-linter |
| 0010 | Lado de leitura separado (CQRS-lite) |
Índice completo em docs/adr.
- Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software (2003)
- Vaughn Vernon, Implementing Domain-Driven Design (2013) e Effective Aggregate Design
- Harry Percival e Bob Gregory, Architecture Patterns with Python
- Martin Fowler, Unit of Work e Specification
- RFC 9457: Problem Details for HTTP APIs
Veja o guia de contribuição.
Matheus Lobo é engenheiro de software, CTO e cofundador da WebFrete. Trabalha com Python, FastAPI, TypeScript e inteligência artificial aplicada, com foco em arquitetura de software e Domain-Driven Design.
- GitHub: @LoboProgrammingg
- LinkedIn: Matheus Lobo
- Projeto complementar: Boas Práticas de Engenharia, guia em português com princípios, arquitetura, testes e segurança, todos com exemplo e teste
MIT © Matheus Lobo Camara