Python Project Architecture Spec
Purpose: Agent context for structuring, extending, or refactoring a Python project. Scope: Generic. Applies to apps, services, and libraries unless noted. Verified against: PyPA Packaging User Guide, Architecture Patterns with Python (Cosmic Python), zhanymkanov/fastapi-best-practices, Real Python.
1. Top-Level Layout
Choose the layout by project type:
| Layout | Use for | Notes |
|---|---|---|
src/ layout |
Libraries, CLI tools, anything built, installed, or published | Requires an install (editable for development) to run. Prevents accidental imports of the in-development copy from the repo root. |
| Flat layout | Applications run directly from the repo (e.g. via uv run) that are never packaged |
Simpler; no build step. |
If uncertain, use src/.
<repo_root>/
├── pyproject.toml # single source of project metadata, deps, tool config
├── README.md # what the project does AND how it is organized
├── .env.example # documented env vars, no secrets
├── src/ # omit this level for flat layout
│ └── <package_name>/ # exactly one top-level package
│ ├── __init__.py
│ ├── main.py # entrypoint / composition root
│ ├── config.py # settings loaded from environment
│ └── ... # see section 2
└── tests/ # mirrors <package_name>/ structure
Rules (both layouts):
- One clear top-level package.
- Keep tooling, scripts, and docs out of the package.
- Configuration comes from the environment. Changing environments must not require code edits.
2. Internal Structure: Choose One Pattern
Pick one pattern based on size and complexity, and apply it consistently.
2A. Layered (by file type): microservices / few feature scopes
<package_name>/
├── api/ # I/O boundary: HTTP routes, CLI commands, message handlers
├── services/ # business logic and use cases
├── repositories/ # data access: DB, external APIs, files
├── models/ # domain entities and schemas
├── core/ # shared utilities, exceptions, logging setup
└── config.py
2B. Feature-First (by domain): apps with many feature scopes
<package_name>/
├── <feature_a>/
│ ├── api.py # thin handlers only
│ ├── service.py # business logic
│ ├── repository.py # data access
│ ├── models.py # feature entities and schemas
│ ├── config.py # optional per-feature settings
│ ├── exceptions.py # feature-specific exceptions
│ └── __init__.py # public API via __all__
├── <feature_b>/
│ └── ...
├── shared/ # cross-feature code ONLY when truly shared
├── config.py # global settings
└── main.py
2C. Clean / Hexagonal: complex business domains, many integrations
<package_name>/
├── domain/ # entities, value objects, business rules. NO framework/infra imports.
├── application/ # use cases (service layer); defines ports (interfaces/Protocols)
├── infrastructure/ # adapters implementing ports: DB/ORM, HTTP clients, queues
├── interfaces/ # entrypoints: web routes, CLI, workers
└── main.py # composition root / bootstrap: wires adapters to ports
Optional for 2C: a Unit of Work to represent atomic updates across repositories.
3. Layer Responsibilities
| Layer | Does | Does not |
|---|---|---|
| API / Interfaces | Parse input, validate, call a service or use case, format output | Business logic, direct DB access |
| Services / Application | Business rules, orchestration, use-case boundaries | Depend on concrete infrastructure (depends on abstractions/Protocols) |
| Repositories / Infrastructure | Persistence and external integrations | Make business decisions |
| Models / Domain | Entities and business invariants | Depend on outer layers, frameworks, or the ORM |
4. Dependency Rules (Non-Negotiable)
- Dependencies flow in one direction:
api -> services -> repositoriesinterfaces -> application -> domain(infrastructure implements application ports)
- Inner layers never import outer layers.
- Dependency inversion: domain models contain no infrastructure imports. The ORM/persistence layer imports the domain model, never the reverse.
- Layered, clean, hexagonal, and onion architectures are all applications of the same rule: high-level modules (domain) must not depend on low-level ones (infrastructure).
- Features do not import each other's internals. Use only the public API (
__all__). - No circular imports. If one appears, the boundary is wrong.
- Inject dependencies (constructor args or framework DI). Do not instantiate infrastructure inside services.
- Wire everything in one composition root (
main.pyor the app factory).
5. Module Conventions
- One clear purpose per module. Group code that changes together.
- [Recommended] Declare a public API with
__all__in package__init__.pyfiles. Unlisted names are internal. - Prefer shallow nesting. Add sub-packages only for genuine sub-domains.
- [Heuristic] Consider splitting a file beyond roughly 300–500 lines, or when it mixes concerns. This is a guideline, not a hard limit.
- Use absolute imports.
- Name files and functions in
snake_case; match file names to their primary concept. - Avoid generic dumping grounds (
utils.py,helpers.py,misc.py) without a clear scope. - Config: one central
config.pyfor small or layered projects. For feature-first projects, per-feature settings classes are acceptable and often preferred.
6. Testing
tests/
├── unit/ # mirrors <package_name>/; no I/O; fake repositories/ports
├── integration/ # real DB / external adapters
└── conftest.py # shared fixtures
- Tests mirror the source structure.
- Business logic must be testable without a framework, DB, or network (use fakes injected through ports).
- With the
src/layout, tests run against the installed (editable) package. - If testing is painful, treat it as a signal that a boundary is wrong.
7. Pattern Selection Guide
| Project type | Layout + Pattern |
|---|---|
| Script / app run directly, never packaged | Flat layout; adopt 2A if it grows |
| Library or distributable CLI | src/ + minimal public API via __all__ |
| Microservice / few feature scopes | 2A Layered (by file type is fine) |
| App with many feature scopes | 2B Feature-first (by domain) |
| Complex domain, many integrations | 2C Clean / Hexagonal |
8. Agent Instructions
- Detect the existing layout and pattern first and follow it. Do not mix patterns.
- Place new code in the layer that matches its responsibility (section 3).
- Never introduce an import that violates section 4.
- When adding a feature under 2B, create its full slice (api / service / repository / models).
- When refactoring a flat project, migrate incrementally:
- Decide the layout (section 1); move to
src/if the project is packaged or distributed. - Extract config to the environment.
- Separate I/O handlers from business logic.
- Extract data access into repositories, with the domain free of ORM imports.
- Group by feature as the number of feature scopes grows.
- Decide the layout (section 1); move to
- Keep tests passing after each step and mirror any moves in
tests/. - If the project type, size, or framework is unclear, ask before restructuring.
- Update the README "Project Structure" section whenever the layout changes.
References
- PyPA – src layout vs flat layout: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/
- pydevtools – src vs flat layout (uv defaults): https://pydevtools.com/handbook/explanation/src-layout-vs-flat-layout.md
- Architecture Patterns with Python (Cosmic Python): https://www.cosmicpython.com
- zhanymkanov – FastAPI Best Practices: https://github.com/zhanymkanov/fastapi-best-practices
- Real Python – Project Layout: https://realpython.com/ref/best-practices/project-layout/