python-architecture

What it does and when to use it

Structure Python backends with explicit dependency direction, ports/adapters, and runtime boundaries. Use when shaping project layout, clean architecture, service boundaries, dependency injection, report rendering boundaries, or transport separation in Python.

How it works

1. Priority: P0 (CRITICAL)
2. Rules
3. Recipe
4. Anti-Patterns
5. References
6. Canonical response anchors

---
name: python-architecture
description: Structure Python backends with explicit dependency direction, ports/adapters, and runtime boundaries. Use when shaping project layout, clean architecture, service boundaries, dependency injection, report rendering boundaries, or transport separation in Python.
metadata:
  triggers:
    files:
      - "pyproject.toml"
      - "requirements.txt"
      - "**/*.py"
    keywords:
      - architecture
      - clean architecture
      - dependency injection
      - service boundary
      - render
      - transport
      - repository pattern
---

# Python Architecture

## **Priority: P0 (CRITICAL)**

## Rules

- Keep domain decisions independent from HTTP, DB, env, and queue clients.
- Define ports where callers need substitution; implement adapters at the edge.
- Compose runtime dependencies in startup or wiring modules.
- Treat contracts, policy, and normalization helpers as standalone modules.

## Recipe

1. **Place pure contracts and policy in domain/application modules**.
2. **Keep adapters thin**: DB, HTTP, bot, MCP, subprocess, storage.
3. **Push workflow orchestration into services** that call contracts and ports.
4. **Separate report formatting from fact gathering**.
5. **Add focused regression tests before moving boundary code**.

## Anti-Patterns

- **No fake clean architecture theatre**: folders must match real ownership.
- **No DB imports in domain policy**.
- **No startup wiring hidden in module globals**.
- **No one-function runtime blobs** spanning parse, dispatch, verify, and notify.

## References

- [Framework Map](../references/framework-map.md)
- [Clean Architecture](references/clean-architecture.md)

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- inject

Versions

The database has no other skills named python-architecture.

Database snapshot: 13.11.2026 · package version 5683b7672568 (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

• 100golang-architecture
  Structure Go code with package-first boundaries, `cmd/` and `internal/`, and explicit dependency wiring. Use when shaping project layout, package ownership, or service boundaries in Go; defer Redis/cache-specific implementation recipes to database skills.
• 100go-architecture-review
  Review Go project architecture: package structure, dependency direction, layering, separation of concerns, domain modeling, and module boundaries. Use when reviewing architecture, designing package layout, evaluating dependency graphs, or refactoring monoliths into modules.…
• 100clean-architecture
  Apply Clean Architecture principles to define layer boundaries, identify dependency violations, and structure domain vs infrastructure code. Use when designing service boundaries, separating business logic from infrastructure, evaluating hexagonal/onion/ports-and-adapters…
• 100clean-architecture
  Use when designing system boundaries, dependency direction, and layered architecture — based on Robert C. Martin's "Clean Architecture." USE FOR: dependency rule enforcement, layer separation, boundary design, use case isolation, screaming architecture, presenter/viewmodel…
• 100707-technologies-hexagonal-architecture
  Use when you need framework-agnostic Hexagonal architecture guidance for Java projects - ports and adapters boundaries, application core independence, driving and driven adapters, dependency direction, infrastructure leakage detection, optional architecture tests, and…
• 100hexagonal-architecture
  Design with ports and adapters to separate business logic from infrastructure. Use when designing a new service, reviewing structural compliance, or deciding how to introduce a new external dependency without coupling the domain.