https://github.com/othmane099/hexagonal-architecture-python
Sample Python REST API implemented according to hexagonal architecture.
https://github.com/othmane099/hexagonal-architecture-python
clean-architecture clean-code code-design code-pattern fastapi hexagonal-architecture ports-and-adapters python repository-pattern rest-api sample-code sqlalchemy
Last synced: about 1 month ago
JSON representation
Sample Python REST API implemented according to hexagonal architecture.
- Host: GitHub
- URL: https://github.com/othmane099/hexagonal-architecture-python
- Owner: othmane099
- Created: 2024-09-02T17:29:40.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-24T08:39:06.000Z (5 months ago)
- Last Synced: 2026-01-24T19:14:51.103Z (5 months ago)
- Topics: clean-architecture, clean-code, code-design, code-pattern, fastapi, hexagonal-architecture, ports-and-adapters, python, repository-pattern, rest-api, sample-code, sqlalchemy
- Language: Python
- Homepage:
- Size: 110 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hexagonal Architecture in Python
This repository contains a sample Python REST API implemented according to hexagonal architecture.
## Commands
```bash
make install # Install dependencies (requires .venv)
make format # Format code (isort, autoflake, black)
make test # Run all tests with pytest
make migrations # Create alembic migration
make migrate # Run alembic migrations
make run # Start FastAPI server on port 8000
```
## Project Structure
```
src/sms/
├── core/ # Domain logic (business rules, independent of infrastructure)
│ ├── domain/ # Models (dataclasses) and DTOs (Pydantic)
│ ├── ports/ # Interfaces: repositories.py, services.py, unit_of_works.py
│ └── services/ # Service implementations (business logic)
├── adapters/ # Infrastructure implementations
│ ├── db/orm.py # SQLAlchemy Data Mapper (imperative mapping)
│ ├── repositories/ # Repository implementations
│ ├── unit_of_works.py # UoW implementations with AsyncSession
│ └── entry_points/api/ # FastAPI endpoints
└── config/
├── containers.py # dependency-injector DI container
└── settings.py # Database and app configuration
```
## Key Patterns
- **SQLAlchemy Data Mapper Pattern**: Tables are defined separately from domain models (dataclasses) and mapped imperatively in `orm.py`. Domain models remain free of ORM dependencies.
- **Dependency Injection**: Uses `dependency-injector` library to decouple core business logic from infrastructure code. This makes the core logic independent of external systems, which can be easily swapped or modified without affecting the core.
- **Unit of Work**: Transaction management via async context managers.
- **Soft Deletes**: All entities have `deleted_at` field for logical deletion.
- **Fakes for Testing**: In-memory fake implementations of repositories in `adapters/repositories/fakes/` for unit testing services without a database.
## Database
- PostgreSQL with asyncpg driver
- Production: port 5435, Test: port 5436
- Alembic for migrations