Software Design in Python - Stop Mixing FastAPI with Business Logic: Fix It with Ports & Adapters

🧱 Build software that lasts. Join the Software Design Mastery waiting list → https://arjan.codes/mastery. In this video, I refactor a FastAPI + SQLAlchemy example into a clean Ports & Adapters (Hexagonal Architecture) design. I separate domain logic from frameworks, introduce domain types and errors, define ports with Protocols, and implement adapters step by step. The result is pure, testable business logic that’s easier to maintain and evolve. 🔥 GitHub Repository: https://git.arjan.codes/2026/ports. 🎓 ArjanCodes Courses: https://www.arjancodes.com/courses. 💬 Join my Discord server: https://discord.arjan.codes. ⌨️ Keyboard I’m using: https://amzn.to/49YM97v. 🔖 Chapters: 0:00 Intro 1:23 What’s the Actual Problem? 3:11 Ports & Adapters in One Minute 4:25 The Demo Use Case (Keep It Tiny, but Real) 5:44 Step 1 — Create Domain Types (Stop Returning API-Shaped Dicts) 9:39 Step 2 — Introduce Domain Errors (No HTTP in the Domain) 12:54 Step 3 — Define the Port (What the Domain Needs) 14:39 Step 4 — Write the Use Case as Pure Logic 19:25 Step 5 — Create SQLAlchemy Adapter Implementing the Port 24:36 Step 6 — FastAPI Adapter Becomes Translation-Only 24:48 Final Thoughts #arjancodes #softwaredesign #python