SOP: Layered Domain Architecture

Use this SOP when the agent keeps violating boundaries, duplicating logic across layers, or producing code that becomes hard to review after a few sessions.

Goal

Make domain boundaries explicit enough that agents can move quickly without silently degrading structure.

Target Model

Within a business domain, prefer this directional flow:

Types -> Config -> Repo -> Service -> Runtime -> UI

Cross-cutting concerns should enter through explicit providers or adapters. Shared utils stay outside the domain and should not accumulate domain logic.

Setup Checklist

• Define the current domains in ARCHITECTURE.md.
• Write allowed dependency directions in ARCHITECTURE.md.
• Record cross-cutting interfaces such as auth, telemetry, and external APIs.
• Add one short note for the hardest current boundary violation.
• Decide what should be enforced mechanically by lint, tests, or scripts.

Execution SOP

1. Map the codebase into domains before touching implementation style.
2. For each domain, identify the allowed layer sequence.
3. Identify all cross-cutting concerns and route them through providers or adapters.
4. Move ambiguous shared logic either into the owning domain or into truly generic utils.
5. Document the rules in ARCHITECTURE.md.
6. Add one executable guardrail for the highest-cost violation.
7. Update quality scoring after the change.

Definition Of Done

• A fresh agent can tell which layer owns a change.
• UI code no longer reaches into repo or external side effects directly.
• Cross-cutting concerns have named entry points.
• At least one important boundary is enforced mechanically.

Repo Artifacts To Update

• ARCHITECTURE.md
• docs/QUALITY_SCORE.md
• docs/design-docs/ when the rationale changed
• docs/PLANS.md or the active execution plan