Skip to content
Skills Library
Programming · Planning

clean-architecture-python

/clean-architecture-python

Use when laying out a Python service packaged with pyproject.toml (FastAPI or another web framework), or adding a feature, endpoint, use case, aggregate or repository to one — which package a module belongs in, which package may import which, and how an endpoint reaches a use case. Not for configuration, dependency or tooling changes.

Licence
GPL-3.0
Last repository change
11.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Use when laying out a Python service packaged with pyproject.toml (FastAPI or another web framework), or adding a feature, endpoint, use case, aggregate or repository to one — which package a module belongs in, which package may import which, and how an endpoint reaches a use case. Not for configuration, dependency or tooling changes.

Original author description

Use when laying out a Python service packaged with pyproject.toml (FastAPI or another web framework), or adding a feature, endpoint, use case, aggregate or repository to one — which package a module belongs in, which package may import which, and how an endpoint reaches a use case. Not for configuration, dependency or tooling changes.

How it works

  1. One package per layer
  2. Use cases
  3. Domain
  4. Guard
Original SKILL.md headings · 62 lines, 513 words
SKILL.md preview
---
name: clean-architecture-python
description: Use when laying out a Python service packaged with pyproject.toml (FastAPI or another web framework), or adding a feature, endpoint, use case, aggregate or repository to one — which package a module belongs in, which package may import which, and how an endpoint reaches a use case. Not for configuration, dependency or tooling changes.
---

# Clean Architecture — Python

The layer rules are those of `architecture-patterns`. This skill maps them onto Python packages.

## One package per layer

| Package | Holds | May import |
|---|---|---|
| `<context>.domain` | aggregates, value objects, domain events | the standard library only |
| `<context>.application` | use cases and the `Protocol`s they call | `<context>.domain` |
| `<context>.infrastructure` | implementations of those `Protocol`s (SQLAlchemy, HTTP clients, files) | `<context>.application`, `<context>.domain` |
| `<context>.api` | routes, the app factory, the wiring of every class | all three |

- Lay out `src/<context>/` with one sub-package per layer, in a single `pyproject.toml`. A new feature goes into the existing layer packages, never into a new top-level package.
- FastAPI, Pydantic, SQLAlchemy and HTTP clients are imported only in `infrastructure` and `api`. Domain and application use `dataclasses` and `typing`.
- ORM models and their mapping live in `infrastructure`; never make a domain class an ORM or Pydantic model.
- Tests live in the two test packages `clean-architecture-testing` defines, never inside `src/`.

## Use cases

- A use case is a class named after the action (`BorrowBook`) with one public method. The route calls it directly: no `Protocol` or ABC in front of it, no `*Service` implementation.
- A command method returns `None`; the caller creates the new id and passes it in. A query returns a frozen `*ViewModel` dataclass defined in `application`, never a domain object.
- Application declares a `Protocol` only where it calls out (repository, gateway). A repository `Protocol` sits in `domain` when it persists an aggregate, in `application` otherwise.
- Who may *read* a resource is checked in the use case. Who may *change* it is an aggregate rule: the mutation method takes the caller's id and raises.
- Wire every class by hand in `api` (one composition module); FastAPI `Depends` appears only in `api`. No DI container.
- One transaction per use-case call, opened and committed in `api` around the call.
- Inside each layer, one sub-package per feature (`application/loans/borrow_book.py`, `infrastructure/loans/sql_loan_repository.py`), never a module at the layer root or a technical package (`repositories`, `services`, `models`). A feature imports no other feature; what two features use moves to a `shared` sub-package of that layer.
- No `ports` or `adapters` package, and no "port" in module, class or docstring.

## Domain

- An aggregate is created through a `classmethod` factory; code outside `domain` never calls the class itself. It is identified by a typed id (`OrderId`, a frozen dataclass or `NewType`), never a raw `str`, `int` or `UUID`.

## Guard

Declare the graph in `pyproject.toml` and add `import-linter` to the dev dependencies; the architecture test of `clean-architecture-testing` runs `lint-imports`:

```toml
[tool.importlinter]
root_package = "<context>"
include_external_packages = true

[[tool.importlinter.contracts]]
name = "Layers import inward only"
type = "layers"
layers = ["<context>.api", "<context>.infrastructure", "<context>.application", "<context>.domain"]

[[tool.importlinter.contracts]]
name = "Domain and application import no framework"
type = "forbidden"
source_modules = ["<context>.domain", "<context>.application"]
forbidden_modules = ["fastapi", "starlette", "pydantic", "sqlalchemy", "httpx"]

[[tool.importlinter.contracts]]
name = "Application features never import each other"
type = "independence"
modules = ["<context>.application.*"]
ignore_imports = ["<context>.application.** -> <context>.application.shared.**"]
unmatched_ignore_imports_alerting = "none"
```

Versions

The database has no other skills named clean-architecture-python.

Database snapshot: 13.11.2026 · package version 8c5c6c63c775 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100clean-architecture-react
    Use when laying out or extending a React / TypeScript front end — which folder a screen, component, hook, use case or API call belongs in, which folder may import which, and how a component reaches the API. Not for build, dependency, environment-variable or tooling configuration.
  • 100clean-architecture-java
    Use when laying out or extending a Java / Spring Boot service built with Maven — which module a class belongs in, which module may depend on which, and how an endpoint reaches a use case.
  • 100python-packaging
    Python package creation and PyPI distribution via pyproject.toml and entry points. Use when publishing a package or setting up build configuration.
  • 100pyproject-generator
    Use when creating or standardizing pyproject.toml for a Python library, service, MCP server or Electron backend.
  • 100flutter-clean-arch
    Use when creating or auditing the layers of a Flutter feature or package - where a use case, repository, datasource, entity or model belongs; whether domain may import Flutter; whether a dependency between layers is inverted. Triggers on "where does this go?" in a feature, or a…
  • 100python-best-practices
    Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.