Hexagonal Architecture (also known as Ports and Adapters) is one of the best patterns for keeping your core business logic pure, testable, and completely decoupled from external noise like databases, APIs, or UI frameworks.

To get started, I will explain these core concepts and how they are applied using FastAPI, PostgreSQL, and Pytest.

The core philosophy

The main idea is simple: Your business logic does not care what database or web framework you use. Instead of building your application in traditional database-centric layers, you put your Domain (Business Logic) at the absolute center. Anything outside that core (FastAPI, PostgreSQL, Celery, External APIs) is considered an “external detail.”

# create a virtualenv, with any tool: poetry, pipenv, virtualenv module, etc 
pip install fastapi uvicorn aiofiles SQLAlchemy psycopg2-binary

project structure

.
├── Dockerfile
├── LICENSE
├── main.py
├── README.md
├── requirements.txt
└── timezone_utils
    ├── database.py
    ├── __init__.py
    ├── models.py
    ├── schemas.py
    └── utils.py

1 directory, 10 files

we define the models, schemas and engine for sqlalchemy and the api in the package timezone_utils

Then inspired on this blog post and the project Timezone boundary builder decided to create a test project using fastapi and postgis to do the timezone lookup using the latitude and longitude.