feature-driven-architecture-python

Feature-Driven Architecture

Match the project's existing structure. When uncertain, read 3-5 existing feature directories to infer the local conventions. Check for import-linter or PyTestArch configuration in pyproject.toml. These defaults apply only when the project has no established convention.

Never rules

These are unconditional. They prevent coupling and boundary erosion regardless of project style.

• Never import another feature's ORM models directly. Features own their models. Cross-feature data access goes through the owning feature's service layer or shared read models. from src.billing.models import Invoice inside src.auth/ is always a defect.
• Never create circular imports between features. If Feature A imports from Feature B and Feature B imports from Feature A, the feature boundaries are drawn wrong. Refactor using events, a shared service, or merge the features.
• Never put business logic in routers/views. Routers handle HTTP concerns (status codes, response formatting). Business logic lives in service.py or domain functions within the feature.
• Never share Pydantic request/response schemas across features. Each feature defines its own schemas. Identical DTOs in two features today will diverge tomorrow — duplication is cheaper than the wrong shared abstraction.
• Never skip boundary enforcement tooling. Setup is 15 minutes — a single independence contract in pyproject.toml and lint-imports in CI. Kraken Technologies found that violations appear even on small teams under deadline pressure, and compound quickly. Code review catches logic issues; import-linter catches structural invariants that are tedious and error-prone to verify manually in diffs.
• Never use ForeignKey across feature boundaries in new code. Use plain integer ID fields between features. The referential integrity cost is real but coupling cost is worse. Shared read models are the escape hatch.
• Never put feature-specific code in the shared layer. shared/ or core/ contains only cross-cutting infrastructure: auth middleware, database session factory, base classes, pagination, response schemas. If it's specific to one feature, it belongs in that feature.
• Never use extend_existing=True for cross-feature read models. It silently merges column definitions into a shared Table object (SQLAlchemy issues #7366, #8925). Use database VIEWs mapped to separate ORM classes instead.