Python Clean Architecture

Python Clean Architecture

Provide Clean Architecture guidance for Python projects, specifically FastAPI APIs. Based on seven core design principles, Pythonic implementations of classic patterns, and a three-layer architecture (Routers → Operations → Database).

Attribution: The principles, patterns, and architectural approach in this skill are inspired by and synthesized from Arjan Codes' courses: The Software Designer Mindset, Pythonic Patterns, and Complete Extension. The specific Pythonic framing (Protocol-based DI, functional pattern progression, three-layer FastAPI architecture) originates from his teaching. This plugin distills those principles into actionable guidance for Claude Code — it is not a reproduction of course content. See also: github.com/arjancodes | youtube.com/arjancodes.

When to Apply

• Scaffolding new FastAPI projects with clean separation of concerns
• Refactoring existing Python code to reduce coupling and increase cohesion
• Adding new components (endpoints, operations, repositories, models)
• Reviewing code for design quality and Pythonic idiom adherence
• Making code testable through dependency injection and Protocol-based abstractions

Core Architecture: Three Layers

Every FastAPI project follows a strict three-layer dependency flow:

Routers (API layer)  →  Operations (business logic)  →  Database (persistence)

Each layer depends ONLY on the layer below it. Never skip layers.

Layer Responsibilities

Routers — HTTP interface. Accept requests, call operations, return responses. No business logic. Act as the composition root where concrete implementations are injected.

Operations — Business logic. Accept a DataInterface (Protocol) parameter for data access. Compute derived values, enforce rules, orchestrate workflows. Never import database modules directly.

Database — Persistence. Implement the DataInterface Protocol using SQLAlchemy, file storage, or any backend. Expose read_by_id, read_all, create, update, delete methods. Return DataObject = dict[str, Any] to decouple from ORM models.