{
  "markdown": "# python-clean-architecture — Claude Code Plugin\n\nA [Claude Code](https://docs.anthropic.com/en/docs/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.\n\n## Attribution\n\nThe principles, patterns, and architectural approach in this plugin are inspired by and synthesized from [Arjan Codes](https://www.arjancodes.com/)' courses:\n\n- **The Software Designer Mindset** — Seven core design principles (cohesion, coupling, abstractions, composition, creation/use separation, data-first design, simplicity)\n- **Pythonic Patterns** — Classic GoF patterns reimagined for Python using Protocol, Callable, functools.partial, and closures\n- **Complete Extension** — Three-layer FastAPI architecture (Routers → Operations → Database) with Protocol-based dependency injection\n\nThe 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](https://www.arjancodes.com/), [github.com/arjancodes](https://github.com/arjancodes), and [youtube.com/arjancodes](https://www.youtube.com/arjancodes).\n\n## Installation\n\n1. Add the marketplace:\n```\n/plugin marketplace add MKToronto/python-clean-architecture\n```\n\n2. Install the plugin:\n```\n/plugin install python-clean-architecture@python-clean-architecture\n```\n\n3. Restart Claude Code (`/exit` then `claude`) to load the plugin.\n\nOr download the repo and test locally without installing:\n\n```bash\ngit clone https://github.com/MKToronto/python-clean-architecture.git\nclaude --plugin-dir /path/to/python-clean-architecture\n```\n\n## Updating\n\n```\n/plugin marketplace update python-clean-architecture\n```\n\nThen restart Claude Code (`/exit` then `claude`).\n\n## Usage\n\n### Automatic (Skill)\n\nThe skill triggers automatically when you ask Claude Code to:\n\n- \"Scaffold a new FastAPI project\"\n- \"Set up clean architecture\"\n- \"Refactor to clean architecture\"\n- \"Add a new endpoint / router / use case / repository\"\n- \"Review my code structure\"\n- \"Apply design patterns in Python\"\n- \"Decouple my code\"\n- \"Make my code testable\"\n\nOr mention: layered architecture, dependency injection, Protocol-based design, Pythonic design patterns.\n\n### Slash Commands\n\n```\n/review-architecture              Review current directory\n/review-architecture src/         Review a specific directory\n/review-architecture app/main.py  Review a specific file\n```\n\nThe review checks:\n- **Architecture layers** — Three-layer separation, no layer skipping, router as composition root\n- **7 design principles** — Cohesion, coupling, abstractions, composition, creation/use, data-first, simplicity\n- **22 code quality rules** — Naming, nesting, types, error handling, imports, structure\n- **Pythonic patterns** — All 25 patterns checked (Strategy as Callable, Factory as dict mapping, Protocol over ABC, etc.)\n\nFindings are reported by severity (Critical / Important / Suggestions) with file/line references and fix snippets.\n\n### All Commands\n\n**Review & Analysis:**\n```\n/review-architecture [path]       Full architecture review (standard or in-depth)\n/review-api-design [path]         Review REST API endpoints for HTTP conventions\n/check-quality [path]             Quick check against 22 code quality rules\n/suggest-patterns [path]          Recommend Pythonic design patterns for your code\n/decouple [path]                  Find tight coupling and suggest DI improvements\n```\n\n**Refactoring:**\n```\n/make-pythonic [path]             Refactor to Pythonic patterns (ABC→Protocol, if/elif→dict, etc.)\n/extract-god-class [path]         Find and split god classes into focused collaborators\n```\n\n**Learning:**\n```\n/learn-architecture [topic]       Learn a design or architecture topic — theory + the Pythonic way + your code\n```\n\n`/learn-architecture` explains rather than edits. Pick any topic from the skill (the 7 principles, three-layer architecture, the 25 Pythonic patterns, GRASP, DDD, code smells, REST, Python craft) and get either a **Lesson** (structured walkthrough) or a **Drill** (interactive Socratic Q&A). Every topic is grounded twice: a canonical illustration from the bundled hotel-API example, plus an analysis of *your* code — whether the concept already applies, could apply, or should apply (a violation to fix). Each lesson ends with trade-offs, the \"commonly confused with\" comparison (Strategy vs State, Adapter vs Facade…), and self-check questions.\n\n**Scaffolding & Testing:**\n```\n/scaffold-api <project-name>      Generate a new FastAPI project with clean architecture\n/add-endpoint <entity-name>       Scaffold a new endpoint across all three layers\n/scaffold-tests [path]            Generate stub-based tests for existing operations\n```\n\n`/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.\n\n## What's Inside\n\n```text\npython-clean-architecture/\n├── .claude-plugin/\n│   ├── plugin.json\n│   └── marketplace.json\n├── README.md\n├── LICENSE\n├── commands/\n│   ├── review-architecture.md\n│   ├── review-api-design.md\n│   ├── check-quality.md\n│   ├── suggest-patterns.md\n│   ├── decouple.md\n│   ├── make-pythonic.md\n│   ├── extract-god-class.md\n│   ├── learn-architecture.md\n│   ├── scaffold-api.md\n│   ├── scaffold-tests.md\n│   └── add-endpoint.md\n└── skills/clean-architecture/\n    ├── SKILL.md\n    ├── references/\n    │   ├── design-principles.md\n    │   ├── layered-architecture.md\n    │   ├── testable-api.md\n    │   ├── testing-advanced.md\n    │   ├── rest-api-design.md\n    │   ├── code-quality.md\n    │   ├── classes-and-dataclasses.md\n    │   ├── function-design.md\n    │   ├── data-structures.md\n    │   ├── error-handling.md\n    │   ├── monadic-error-handling.md\n    │   ├── types-and-type-hints.md\n    │   ├── project-organization.md\n    │   ├── context-managers.md\n    │   ├── decorators.md\n    │   ├── async-patterns.md\n    │   ├── pydantic-validation.md\n    │   ├── pattern-matching.md\n    │   ├── grasp-principles.md\n    │   ├── domain-driven-design.md\n    │   ├── pythonic-patterns.md\n    │   └── patterns/          (25 pattern files)\n    │       ├── strategy.md\n    │       ├── registry.md\n    │       ├── command.md\n    │       ├── builder.md\n    │       ├── repository.md\n    │       ├── cqrs.md\n    │       └── ...\n    └── examples/\n        └── fastapi-hotel-api/\n            ├── main.py\n            ├── models/\n            ├── operations/\n            ├── routers/\n            └── db/\n```\n\n## Key Concepts\n\n### Three-Layer Architecture\n\n```\nRouters (API)  →  Operations (business logic)  →  Database (persistence)\n```\n\nEach layer depends only on the layer below. The router is the composition root where concrete DB implementations are injected into operations via the `DataInterface` Protocol.\n\n### Seven Design Principles\n\n1. High Cohesion — Single responsibility per unit\n2. Low Coupling — Minimize dependencies, Law of Demeter\n3. Depend on Abstractions — Protocol + Callable for DI\n4. Composition over Inheritance — Never mixins, shallow hierarchies only\n5. Separate Creation from Use — Dict mapping, creator functions, one composition root\n6. Start with the Data — Information Expert, fix data structures first\n7. Keep Things Simple — DRY, KISS, YAGNI (but avoid hasty abstractions)\n\n### Pythonic Pattern Defaults\n\n- Protocol over ABC (unless shared superclass state needed)\n- `functools.partial` over wrapper classes\n- Closures over factory class hierarchies\n- `Callable` type aliases over single-method abstract classes\n- Dict mapping over if/elif chains\n- Readability over dogmatic functional purity\n\n25 design patterns implemented the Pythonic way:\n\n**Core Patterns:**\n- **Strategy** — `Callable` type alias, pass functions as args\n- **Abstract Factory** — Tuples of functions + `functools.partial`\n- **Bridge** — `Callable` type alias replaces abstract reference\n- **Command** — Functions returning undo closures\n- **Pub/Sub** — Dict-based `subscribe(event, handler)` / `post_event(event, data)`\n- **Registry** — `dict[str, Callable]` mapping + `**kwargs` unpacking\n- **Template Method** — Free function + Protocol parameter\n- **Pipeline** — `functools.reduce` for composition\n- **Callback / Wrapper / Builder** — Functional patterns for event handling, interface translation, and configuration\n\n**Extended Patterns:**\n- **Value Objects** — Subclass built-in types with `__new__` validation, or frozen dataclass\n- **Event Sourcing** — Immutable events, append-only EventStore, projection functions\n- **CQRS** — Separate write model + read projection, projector function after writes\n- **Builder** — Fluent API with `Self` return type, `.build()` returns frozen product\n- **Unit of Work** — Context manager wrapping transaction: commit on success, rollback on error\n- **Singleton** — Module-level instance (preferred), or metaclass with `_instances` dict\n- **State** — Protocol-based state objects, context delegates to current state\n- **Adapter** — Protocol interface + `functools.partial` for single-method adaptation\n- **Facade** — Simplified interface class, `functools.partial` to bind dependencies\n- **Retry** — `@retry` decorator with exponential backoff, fallback strategies\n- **Lazy Loading** — `functools.cache`, `cached_property`, generators, `__getattr__`\n- **Repository** — Protocol interface for CRUD, concrete implementations per storage backend\n- **Fluent Interface** — Methods return `self` for chaining, domain-specific verbs for readability\n- **Plugin Architecture** — Config-driven creation, `importlib` auto-discovery, self-registering modules\n\n## Example Output\n\nSee the [full example review](https://mktoronto.github.io/python-clean-architecture/#example) — a color-coded `/review-architecture` run against a test bookstore-api project (15 findings with before/after code).\n\n## Also available for\n\n- **Codex CLI** — [python-clean-architecture-codex](https://github.com/MKToronto/python-clean-architecture-codex) (agent skill for Codex)\n",
  "bytes": 10516,
  "sha": "ce44e5530c6be41f95ab1d9302f9af57637cdb93d6b0801db7c96f0a672377db",
  "repo_slug": "mktoronto/python-clean-architecture",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_mktoronto_python_clean_architecture_pyth_cd6e9c59/readme"
}