Changes

Architecture Improvement

• Refactored exceptions from service_layer to domain layer
• Pure Python domain exceptions (no HTTP coupling)
• Explicit HTTPException conversion in API routes
• Hexagonal Architecture compliance improvement

New Exception Hierarchy

DomainError
├── EntityNotFoundError
│   └── ItemNotFoundError
├── EntityValidationError
│   └── ItemValidationError
├── ExternalServiceError
│   └── ExternalAPIError
└── AuthenticationError
    ├── InvalidCredentialsError
    ├── SessionExpiredError
    └── InvalidTokenError

Breaking Changes

• Import path changed: domain.exceptions instead of service_layer.exceptions
• ServiceError removed, use DomainError as base class
• status_code/error_type attributes removed from exceptions

Migration Guide

# Before
from service_layer.exceptions import ItemNotFoundError

# After
from domain.exceptions import ItemNotFoundError

# API Route - explicit HTTPException conversion
try:
    item = await service.get_item(item_id)
except ItemNotFoundError as e:
    raise HTTPException(status_code=404, detail=str(e))

VOID v1.0.0

DDD + Hexagonal Architecture FastAPI Boilerplate

Production-ready boilerplate for building FastAPI applications with Domain-Driven Design and Hexagonal Architecture patterns.

Features

• Domain-Driven Design with clean layer separation
• Hexagonal Architecture (Port-Adapter pattern)
• FastAPI with async/await throughout
• MongoDB with Motor (async driver)
• AWS SQS FIFO queue integration
• Unit of Work for transactional consistency
• Three entrypoints: API, Worker, CLI

Tech Stack

• Python 3.9+
• FastAPI
• MongoDB (Motor)
• AWS SQS (FIFO)
• httpx

Quick Start

./void run api      # Start API server
./void run worker   # Start SQS worker
./void run job <name>  # Run CLI job