The use case stays. Everything around it changes.

bisslog is my open-source library for hexagonal architecture in Python. Business rules live in plain use cases with no framework code; HTTP, queues, Lambda and databases plug in as adapters. It is not a framework: the core has no external dependencies.

Animation: a use case in the centre stays the same while the entry point changes from Flask to AWS Lambda, FastAPI, Axum, Express and NestJS, and the adapters change from RabbitMQ and MongoDB to Kafka and SQL Server.
Frame by frame, the entry point, the adapters and even the language change. The use case in the middle does not.

The problem

In most services the business logic is written inside the framework: a Flask route opens the database client, applies the rules and formats the response. It works until the service has to run as a Lambda, read from a queue or move from MongoDB to PostgreSQL. Then the rules have to be rewritten, because they were never apart.

Diagram: a use case written inside Flask, with a PyMongo handler inside the use case talking to MongoDB. FastAPI and AWS Lambda are shown as other entry point technologies it cannot move to.

The idea

Each service is organised around its use cases, which say what the system does. How it is triggered (HTTP, EventBridge, Lambda, a CLI) and where the data lives (MongoDB, PostgreSQL, S3) are adapters behind ports that the use cases define. An entry point is just another adapter.

Diagram: possible entry points (AWS Lambda, FastAPI, Flask, Django, RabbitMQ, Kafka) are mapped to a microservice whose use cases talk to ports for the database, publisher, notifier, file upload and WebSockets; adapters such as PostgreSQL, PyMongo and RabbitMQ implement those ports.

Service and use-case metadata is written in YAML, so the HTTP routes, Lambda handlers and FastAPI apps can be generated instead of written by hand. Because the rules are declared apart from any framework, translating a use case to another stack, by hand or with AI assistance, is a contained task.

Packages

Read more

Want this separation in your services?

Tell me on LinkedIn about the system. I answer every message.