Package Map

A navigation map of the Django apps in apps/ — what each is for, and which way dependencies flow. Use it to find where a concern lives and to gauge the blast radius of a change before making it.

This is a role map, not a strict layering. The import graph is a connected graph, not an acyclic stack of layers: foundational apps are imported almost everywhere, and a few apps import very widely. The direction below describes the dominant flow, not an invariant the code never crosses — that is why there is no import-linter contract enforcing it (see the note at the end).

Dependency direction

Dependencies flow downward: entry points depend on domain apps, which depend on the foundation. The foundation depends on nothing above it.

flowchart TD
    EP["Entry points<br/>api · web · admin · dashboard · prelogin · users · oauth · sso"]
    DOM["Domain & runtime<br/>experiments · chatbots · pipelines · custom_actions · service_providers<br/>chat · channels · participants · slack · documents · files"]
    FEAT["Evaluation, analytics & support<br/>evaluations · human_annotations · annotations · assessments<br/>trace · events · cost_tracking · usage_metrics · analysis · moderation · ocs_notifications · banners · help · filters · mcp_integrations"]
    FND["Foundation<br/>teams · utils · generics · web · audit · data_migrations"]

    EP --> DOM
    EP --> FEAT
    DOM --> FEAT
    FEAT --> DOM
    DOM --> FND
    FEAT --> FND
    EP --> FND

Tiers

Foundation

Cross-cutting infrastructure imported almost everywhere. Changes here have the widest blast radius.

Domain & runtime

The chatbot model and the machinery that runs conversations.

Evaluation, analytics & support

Features layered on top of the domain, plus supporting services.

Entry points

Top of the stack — nothing imports these; they wire the domain to the outside world.

Where code goes within an app

Services

An operation that more than one entry point uses (web view, API view, Celery task, channel) lives in a function in the owning app's services module. Each entry point calls that function instead of reimplementing the operation. The function:

• takes the team explicitly, or derives it from a team-scoped object it is given
• owns its transaction and any task dispatch

Views and serializers only parse input and format output.

Start with a single services.py. When it grows large or covers several unrelated concerns, turn it into a services/ package with one module per concern, as apps/cost_tracking/services/ does (pricing.py, estimation.py, recorder.py, reporting.py). Do not let services.py collect every operation the app has.

Helpers

Before writing a helper, search for an existing one that does the same thing. To reuse a helper from another module, move it rather than importing it from where it is:

apps/utils must not import from domain apps.

Before moving or deleting a helper, search the whole repo for its name to find every caller and which apps they are in. Include uses through aliases, re-exports in __init__.py, star imports, and string references (Celery task names, URL configs, templates).

Blast radius

These apps are dependency magnets — a large fraction of the codebase imports them, so changes ripple widely. Treat their public surfaces as contracts and lean on the guard tests when touching them:

Why no import-linter contract

An import-linter layering contract was considered but rejected: the tool's current release forces a downgrade of a runtime dependency (typer, pulled in by taskbadger and transformers) to resolve, which is not worth it for a dev-only check. The import graph is also genuinely cyclic between the domain and feature tiers, so a strict layering contract would not hold without extensive ignore_imports exceptions. The existing scripts/check_inline_imports.py guard already covers the one import rule that is mechanically enforced (no unjustified function-level imports).