Structure emerges whether you choose it or not
A project without a deliberate structure develops one anyway, usually organised by what was written when. That structure is invariably worse than one chosen at the start.
The cost of deciding structure early is an hour. The cost of imposing it later is a refactor across the whole codebase.
Separate business logic from the framework
- Business rules in modules that import nothing framework-specific
- Framework code that calls into them
- Data access behind an interface, not scattered through logic
- Configuration passed in rather than read globally
That separation makes business logic testable without spinning up a web framework, and it means a framework change is a rewrite of the edges rather than of the system.
Organise by feature, not by type
| Instead of | Prefer |
|---|---|
| models/, views/, services/ | orders/, invoicing/, reporting/ |
| One large utilities module | Utilities near what uses them |
| Everything importable from everywhere | Explicit, limited public interfaces |
| Deep nesting | Flat until it genuinely needs depth |
Feature-based organisation means a change to one area touches one directory, which makes both work and review easier.
Keep dependencies pointing one way
Business logic should not import from the web layer. The web layer imports business logic. Circular imports are a symptom that the boundaries are wrong.
When you find yourself fighting import order, the structure is telling you something.
Consistency over correctness
There is no single right structure for a Python project. There is enormous value in a project where everything follows the same pattern, because unfamiliar code becomes readable.
Decide, document it briefly, and apply it consistently.