Project Architecture

Layout and Packaging

proj/
├── pyproject.toml        # PEP 621 metadata, deps, tool config — one file
├── src/
│   └── proj/
│       ├── __init__.py
│       ├── cli.py        # console entry point
│       └── services/
└── tests/
    ├── unit/
    └── integration/

[project]
name = "proj"
version = "0.1.0"
dependencies = ["httpx>=0.27"]

[project.scripts]
proj = "proj.cli:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

The src layout matters: with src/, tests cannot accidentally import your package from the working directory instead of the installed distribution — the classic "works locally, fails in CI" trap. [project.scripts] installs a real console command; pin dev tools in an optional dependency group ([project.optional-dependencies] dev) so environments stay reproducible.

Layering and Boundaries

Keep domain rules pure and push I/O to the edges:

cli / api adapters  →  services (use cases)  →  domain (pure logic)
        ↑                       ↑
   config (env)          repositories (db, http)

Rules that keep the diagram true:

• domain/ imports nothing from services or adapters — no HTTP, no os.environ
• services accept collaborators as parameters (constructor injection), so tests pass fakes
• cli.main() is thin: parse args, load config, call one service, map result to exit code
• Public surface is explicit — re-export in __init__.py

Configuration lives in one module that reads os.environ once, validates it, and returns an immutable object. Domain code receives that object; it never touches os.environ directly. The payoff is testability: make_service(client=fake_http) needs no monkeypatching.

Testing Strategy and CI/CD

Match test scope to blast radius:

CI runs gates in cheap-to-expensive order so failures surface fast:

- run: ruff check . && black --check .
- run: mypy src
- run: pytest -n auto --cov=src --cov-fail-under=80

Cache the virtualenv between runs; matrix across the Python versions you support (3.11, 3.12, 3.13). CD publishes only from tags: python -m build, twine check dist/*, then upload with provenance/trusted publishing. Keep main green — broken merges cost far more than slow pipelines.