interface:
  display_name: "Codebase Design"
  short_description: "Design clear code, UI and domain ownership"
  default_prompt: "Use $codebase-design to simplify these boundaries and define clear public contracts, loading UI or domain guidance where relevant."

# Domain-driven design

Apply when business meaning or rules determine the structure. Start with actual use cases, terminology + counterexamples from domain knowledge; unfamiliar vocabulary stays an open question, not an invented model.

| Decision | Design test |
| --- | --- |
| Shared language | Do domain experts, code and tests use the same term for the same concept within this context? |
| Bounded context | Where do meaning, rules or ownership change? Keep each model coherent; map actual context relationships + translation points with Mermaid when boundaries are involved. A context is not automatically a service or database. |
| Entity / value | Does identity persist through change, or does equality depend on attributes? Model the former as identity-bearing; prefer immutable values for the latter when supported by the domain. |
| Aggregate | Which invariants must hold atomically? Choose the smallest consistency boundary that protects them; route changes through its owner and test concurrent/conflicting operations. Do not group an entire object graph merely because tables relate. |
| Cross-context contract | Define exchanged meaning, ownership, permitted consistency delay + failure/retry behavior. Translate differing models instead of forcing one universal entity across contexts. |

- Put business policy at its domain owner; keep transport/storage details from dictating the model. Reuse existing seams; a repository interface per entity or a domain-service class per action is not a requirement.
- Simple CRUD can remain simple. DDD alone does not justify microservices, CQRS, event sourcing, an event bus or new layers. Introduce a pattern only for a current domain/consistency need.
- Verify invariants through real use cases, rejected transitions + relevant concurrency/retry failures. A context diagram or renamed class does not prove the rules hold.

Concept references: [Bounded contexts](https://martinfowler.com/bliki/BoundedContext.html) · [Aggregates](https://martinfowler.com/bliki/DDD_Aggregate.html).

# Ownership + public contracts

- Evidence = accepted behavior + actual owner, callers and dependencies. Identify knowledge leaking into callers: policy, storage shape, ordering, state, errors or repeated coordination.
- Change = delete an unnecessary concept, consolidate behavior or deepen the existing owner's interface. A renamed pass-through wrapper does not hide complexity; an internal test shortcut alone does not justify a new public seam.
- Contract = meaningful entry points, inputs/results, invariants, errors + side effects. Show a real caller before/after; name what callers no longer need to know.
- Alternatives = compare materially different contracts only when the trade-off matters. Judge caller simplicity, hidden policy, coupling + migration cost; do not manufacture options for a settled local change.
- Proof = trace affected callers, stored data, keys/caches, routes + integration boundaries. Verify preserved public behavior and the failure the old structure permitted. Report the selected owner, removed complexity + unresolved trade-offs.

# UI ownership

Use the existing design system + actual consumers to locate the decision's owner.

| Decision | Closest owner |
| --- | --- |
| Reusable visual value | Existing token/theme |
| Basic control behavior | Primitive / atom |
| Repeated interaction or composition | Component / molecule / organism |
| Page arrangement | Layout / template / page |

- These are responsibilities, not required folders or extraction targets. Keep a true one-off constraint local; component extraction must remove repeated visual/interaction knowledge or establish a meaningful composed contract.
- Check existing variants before adding props or another component. Reuse styling without merging components whose behavior and semantics differ.
- Consolidate touched consumers at the chosen owner; avoid parallel editable values in documentation, theme and components. Follow the project's existing token mechanism rather than introducing generation or synchronization tooling.
- Exercise affected responsive, loading, empty, error, disabled + focus states as applicable. Verify semantic names/roles, keyboard behavior and visual output; component reuse alone proves none of these.