Hexagonal Architecture in Python — ELI5

Think about a game console like a PlayStation. It has ports — an HDMI port for the TV, a USB port for the controller, a network port for the internet. The console does not care which brand of TV you plug in. Any HDMI-compatible screen works.

Hexagonal Architecture (also called Ports and Adapters) makes your Python code work the same way. Your application is the console. It has “ports” — openings where the outside world plugs in. And “adapters” are the cables that connect specific things to those ports.

Want to store data? There is a port for that. Plug in a PostgreSQL adapter today, swap it for a MongoDB adapter tomorrow. The core application does not change.

Want to receive requests? There is a port for that too. Plug in a web adapter, a command-line adapter, or a message-queue adapter. The business logic inside stays identical.

The hexagon shape is just a drawing convention — it has nothing to do with the number six. The point is that your application has many flat sides (ports) where different outside systems can connect.

Why does this help? Because the real world is messy and changes often. Databases get replaced. APIs evolve. New interfaces appear. If your important code is tangled up with those details, every change is painful. With hexagonal architecture, changes stay at the edges.

The one thing to remember: Hexagonal Architecture gives your app pluggable ports so you can swap any external system without rewriting the core logic.