# Python Architecture

> 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.

- Skill: `hoangnguyen0403/python-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hoangnguyen0403/python-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/python-architecture/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/hoangnguyen0403/python-architecture

---


# 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