# 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 -> repositories`
  - `interfaces -> 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.py` or 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__.py` files. 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.py` for 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:
  1. Decide the layout (section 1); move to `src/` if the project is packaged or distributed.
  2. Extract config to the environment.
  3. Separate I/O handlers from business logic.
  4. Extract data access into repositories, with the domain free of ORM imports.
  5. Group by feature as the number of feature scopes grows.
- 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/
