Project layout

A project that has grown by accident is hard to read. A fixed layout means that anyone, including you in six months, knows where to look.

Here is the example project:

triage-service/
├─ pyproject.toml        name, version, dependencies, tool settings
├─ README.md             how to run it, in five lines
├─ .gitignore            keeps .venv/ and .env out of Git
├─ src/
│  └─ triage/            the package people import
│     ├─ __init__.py
│     ├─ models.py       data shapes (typed, validated)
│     └─ cli.py          thin entry point; logic stays elsewhere
└─ tests/
   └─ test_models.py     mirrors the package; one test file per module

Three habits keep this tidy, each with a reason:

1. Put code under src/. Your tests then import the installed package, exactly as a user would. If you keep the code next to the tests, a packaging mistake can hide, because Python finds your files by accident.
2. Keep entry points thin. cli.py (or, later, a web route) reads input and calls a function. The real logic lives in other modules, where you can test it without a terminal.
3. Keep settings out of the code. When the project needs settings, such as an API key, the repository holds a file called .env.example that lists the names only. Real values never get committed (Level 0, module 6 covers this). The small example project has no settings yet, so it has no such file.