Hexagonal DDD 5 Services Example

This workspace demonstrates a Domain-Driven Design (DDD) approach using the Hexagonal (Ports and Adapters) architecture pattern in Python. Five simple services are provided as separate Docker containers to illustrate bounded contexts and clean separation of responsibilities.

Business Domain

The example domain is a simplified e-commerce system with the following bounded contexts:

• Users – customer identity and profile management
• Products – catalog and pricing information
• Orders – creating and paying for orders (shown in detail)
• Inventory – stock tracking
• Shipping – shipments for orders

Each service encapsulates its own domain model, application use cases, and infrastructure adapters. The orders service has a more complete implementation showing entities, value objects, domain events, repositories, and HTTP adapter.

Architectural Principles

The code follows guidelines articulated by the user:

• Domain layer defined first with entities, value objects, invariants.
• Application layer contains use case classes interacting with repository interfaces (ports) and publishing domain events.
• Infrastructure layer provides adapters implementing ports (e.g. in-memory repositories, Flask web server).
• No direct dependencies from domain to infrastructure or UI.
• Dependencies injected explicitly; ports defined as protocols.
• Separate modules for each layer, small focused responsibilities (SRP).
• Dockerfiles show how each service can be containerized; docker-compose brings them together.

Running the example

Build and start all services:

cd /Volumes/External/Code/hexagonal-ddd-5-services
docker-compose build
docker-compose up

The orders service listens on port 8000; use it to create/pay orders:

curl -X POST http://localhost:8000/orders -H 'Content-Type: application/json' -d \
  '{"user_id":"<uuid>","items":[{"product_id":"<uuid>","quantity":1}]}'

curl -X POST http://localhost:8000/orders/<order_id>/pay

Other services are placeholders and expose simple HTTP servers.

Next Steps

• Expand each service with full use cases, repositories (e.g. SQL), events, and integration tests.
• Implement shared event bus or message broker for inter-service communication.
• Add configuration, logging, metrics, authentication (per guidelines).
• Write unit tests and integrate with CI/CD.

This repository serves as a starting point to demonstrate how DDD and hexagonal architecture can guide the design of a multi-service Python system.