python-clean-architecture

python-clean-architecture — Claude Code Plugin

A Claude Code plugin that provides Clean Architecture guidance for Python/FastAPI projects. Scaffold, review, and refactor Python projects with design principles and Pythonic patterns — directly inside Claude Code.

Attribution

The principles, patterns, and architectural approach in this plugin are inspired by and synthesized from Arjan Codes' courses:

• The Software Designer Mindset — Seven core design principles (cohesion, coupling, abstractions, composition, creation/use separation, data-first design, simplicity)
• Pythonic Patterns — Classic GoF patterns reimagined for Python using Protocol, Callable, functools.partial, and closures
• Complete Extension — Three-layer FastAPI architecture (Routers → Operations → Database) with Protocol-based dependency injection

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. If you find this useful, consider supporting Arjan's work at arjancodes.com, github.com/arjancodes, and youtube.com/arjancodes.

Installation

1. Add the marketplace:

/plugin marketplace add MKToronto/python-clean-architecture

2. Install the plugin:

/plugin install python-clean-architecture@python-clean-architecture

3. Restart Claude Code (/exit then claude) to load the plugin.

Or download the repo and test locally without installing:

git clone https://github.com/MKToronto/python-clean-architecture.git
claude --plugin-dir /path/to/python-clean-architecture

Updating

/plugin marketplace update python-clean-architecture

Then restart Claude Code (/exit then claude).

Usage

Automatic (Skill)

The skill triggers automatically when you ask Claude Code to:

• "Scaffold a new FastAPI project"
• "Set up clean architecture"
• "Refactor to clean architecture"
• "Add a new endpoint / router / use case / repository"
• "Review my code structure"
• "Apply design patterns in Python"
• "Decouple my code"
• "Make my code testable"

Or mention: layered architecture, dependency injection, Protocol-based design, Pythonic design patterns.

Slash Commands

/review-architecture              Review current directory
/review-architecture src/         Review a specific directory
/review-architecture app/main.py  Review a specific file

The review checks:

• Architecture layers — Three-layer separation, no layer skipping, router as composition root
• 7 design principles — Cohesion, coupling, abstractions, composition, creation/use, data-first, simplicity
• 22 code quality rules — Naming, nesting, types, error handling, imports, structure
• Pythonic patterns — All 25 patterns checked (Strategy as Callable, Factory as dict mapping, Protocol over ABC, etc.)

Findings are reported by severity (Critical / Important / Suggestions) with file/line references and fix snippets.

All Commands

Review & Analysis:

/review-architecture [path]       Full architecture review (standard or in-depth)
/review-api-design [path]         Review REST API endpoints for HTTP conventions
/check-quality [path]             Quick check against 22 code quality rules
/suggest-patterns [path]          Recommend Pythonic design patterns for your code
/decouple [path]                  Find tight coupling and suggest DI improvements

Refactoring:

/make-pythonic [path]             Refactor to Pythonic patterns (ABC→Protocol, if/elif→dict, etc.)
/extract-god-class [path]         Find and split god classes into focused collaborators

Scaffolding & Testing:

/scaffold-api <project-name>      Generate a new FastAPI project with clean architecture
/add-endpoint <entity-name>       Scaffold a new endpoint across all three layers
/scaffold-tests [path]            Generate stub-based tests for existing operations

/scaffold-api generates a full project structure with Pydantic models, operations, routers, database layer, and tests. /add-endpoint adds a new entity to an existing project — it creates files across all three layers (router + operations + DB model + Pydantic models + tests) and wires them into main.py. /scaffold-tests generates DataInterfaceStub-based tests for existing operations without requiring a database.

What's Inside