Architecture Model

​

Scopes

• roots is required and its entries must not be nested inside one another, so every scanned file belongs to exactly one root. Independent package trees in a monorepo are expressed as multiple roots.
• tests defaults to ["tests"].
• tooling defaults to empty.

​

Ownership roots

src/my_package/                 # product root
└── sources/                    # structural group
    └── region_a/               # ownership root
        ├── orders/             # domain
        │   └── main/
        └── partners/           # domain
            └── importing/      # subdomain
                └── main/

​

Roles

​

Domains: leaf or branch

• An ownership root (by default the package root, for example src/my_package/) holds only its package protocol modules, deliberate public facades where supported, and domain packages. No role files live at the ownership root.
• A leaf domain holds the actual work directly: main/, _helpers/, classes/, and the role files (models.py, types.py, constants.py, exceptions.py).
• A branch domain holds only named subdomains, each of which is itself built from the roles.

src/my_package/
├── __init__.py                 # public re-export surface only
├── config/                     # a leaf domain: roles live directly here
│   ├── models.py
│   ├── types.py
│   ├── constants.py
│   ├── exceptions.py
│   ├── main/
│   │   └── load_config.py      # published orchestrator
│   └── _helpers/
│       ├── discovery.py
│       ├── parse.py
│       └── validate.py
└── billing/                    # a branch domain: named subdomains only
    ├── invoices/
    │   ├── main/
    │   ├── _helpers/
    │   └── models.py
    └── payments/
        └── ...

​

Vocabulary lives with its owner

​

Shared domain prefixes

billing_annotation_export/
billing_annotation_validation/
billing_events/

billing/
├── annotation_export/
├── annotation_validation/
└── events/

​

Root public facades

# src/my_package/orders_api.py
from my_package.orders.models import Order

__all__ = ("Order",)

• a direct alias or re-export;
• a one-statement forwarding function, including async forwarding;
• an overload declaration paired with a supported implementation;
• a constrained context-manager wrapper; or
• a trivial subclass of one imported base.

• FFR307 allows the otherwise-disallowed direct root module.
• FFR403 allows its deliberate re-export shape.
• FFR310 keeps the dependency direction one-way: product runtime modules must import the owning domain directly, not route inward through the facade. Tests, tooling, and external consumers may import the facade.

​

Containers: flat or grouped

• Flat: modules sit directly in the package, up to a cap (max_helpers_container_modules, default 10, for _helpers/; max_main_container_modules, default 20, for main/).
• Grouped: every module is grouped into one level of concern subfolders (buckets), each bucket holding modules up to the same cap.

​

Entry modules

• exactly one public function (the entry point);
• at most two private functions in that file;
• top level contains only imports and function definitions, nothing else.

# config/main/load_config.py  (an entry module)
from __future__ import annotations

from pathlib import Path

from fensu.config._helpers.defaults import build_config
from fensu.config._helpers.discovery import locate_config
from fensu.config._helpers.parse import parse_config_source
from fensu.config._helpers.validate import validate_config
from fensu.config.models import Config, ConfigSource


def load_config(start: Path | None = None) -> Config:
    """The one public entry point; it may call as many helpers as it needs."""
    source: ConfigSource = locate_config(start)
    raw_config = parse_config_source(source)
    validate_config(raw_config)
    return build_config(raw_config)

​

Default thresholds

​

Tooling layout

• Direct scripts/*.py files are thin command adapters: one public main(), an optional _parse_args() or _build_parser(), imports, the if __name__ == "__main__" guard, and delegation to an imported main/ entry. scripts/__init__.py is exempt.
• A tool implementation uses one ownership level then a role:

scripts/
├── fetch_data.py               # thin command adapter
└── data_snapshot/
    ├── main/
    ├── _helpers/
    ├── classes/
    ├── models.py
    ├── types.py
    ├── constants.py
    └── exceptions.py

​

Test layout

• Mirrored. Tests live under a scope of unit/, integration/, or e2e/, then mirror the source path they exercise. A test for src/my_package/config/main/ lives at tests/unit/src/my_package/config/main/. Set test_scopes if your project uses a different set.
• Named for behavior. Test files start with test_, and each test is test_given_<state>_when_<action>_then_<outcome>, so the precondition, action, and expectation are readable without opening the body.
• Dataclass-backed cases. Tests parametrize over a local frozen dataclass rather than tuples or dicts. Each case carries a description and at least one expected_ field, and the test asserts against that field. Case ids come from lambda case: case.description, so a failure names the behavior.

tests/unit/src/my_package/config/main/
├── _test_types.py              # local test-case dataclasses
└── test_load_config.py         # tests parametrized over those cases

# _test_types.py
from dataclasses import dataclass


@dataclass(frozen=True)
class LoadConfigCase:
    description: str
    source: str
    expected_root: str

​

Related