coding-python-clean-architecture

Structure Python projects with layered ports-and-adapters architecture and review layer dependency violations.

1|Updated Jun 23, 2026
One-click install
npx skills add https://github.com/bitranox/bitranox-skills --skill coding-python-clean-architecture-bitranox
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: coding-python-clean-architecture
Source: https://github.com/bitranox/bitranox-skills/tree/main/plugins/bitranox/skills/coding-python-clean-architecture
Command: npx skills add https://github.com/bitranox/bitranox-skills --skill coding-python-clean-architecture-bitranox

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Python codebases often tangle business logic with frameworks, databases, and I/O, making them hard to test, change, and reason about. This Skill provides a complete layered architecture methodology that keeps the domain pure and dependencies pointing inward. ## Core Features & Use Cases - Layered Architecture Guidance: Defines domain, application, adapter, and composition layers with strict inward-only dependency rules, Protocol-based ports, and immutable frozen dataclasses for entities and value objects. - Reliability Patterns: Provides standard port contracts for Unit of Work, Outbox, Idempotency, Clock, and IdProvider, plus deterministic lock ordering and timeout handling. - Four Operating Modes: Covers full application generation, architecture review with severity-rated checklists, library/SDK development with SemVer and plugin entry points, and single-file script mode with PEP 723 support. - Use Case: When starting a new FastAPI-backed service, use this Skill to scaffold a domain-centric folder layout where use cases are testable with in-memory adapters and the framework appears only in the composition root. ## Quick Start Ask the AI to structure a new Python project using layered ports-and-adapters architecture with a pure domain and testable use cases.

Frequently Asked Questions about coding-python-clean-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure a Python project with clean architecture?▼

Organize code into four layers: domain (pure frozen dataclasses, no I/O), application (use cases and Protocol ports), adapters (framework and persistence implementations), and a composition root that wires everything. Dependencies must point inward only, enforced with import-linter contracts.

What is the ports and adapters pattern in Python?▼

Ports are Protocol classes defined in the application layer that declare what the business logic needs, such as a repository or clock. Adapters in the outer layer implement those protocols, making databases and frameworks swappable plugins to the core.

Should I use dataclasses or Pydantic for domain entities?▼

Use @dataclass(frozen=True, slots=True) for domain entities and value objects to keep the domain pure and dependency-free. Reserve Pydantic BaseModel for boundary validation and serialization in adapters, converting to domain types at the edge.

How do I test use cases without a real database?▼

Write unit tests against in-memory adapter implementations of your ports, and run the same contract test suite against every adapter implementation. A Testing API with superpowers like seeding data and freezing time keeps tests decoupled from production structure.

When should I not use layered clean architecture?▼

Skip it when a project already follows a different established architecture. Single-file scripts and throwaway prototypes do not need the full layout either; they route to script mode, which keeps logical layer boundaries inside one stdlib-only file.

How do I prevent circular imports between Python layers?▼

Break cycles by introducing a Protocol in the inner layer that the outer layer implements, inverting the dependency. Enforce the rules mechanically with import-linter layer and independence contracts so violations fail CI.