kyaulabs/prism/systems-design

Decide: ADR, RFC, or neither?

When in doubt, write an ADR. They are cheap and future readers thank you.

C4-lite notation

Three zoom levels. Sketch in the ADR/RFC; don't aim for completeness.

1. Context — the system and its external actors/users. One box, arrows in/out.
2. Container — major deployable/runnable units (the app, the DB, the CDN,

any worker). One box each, with the tech noted inside.

1. Component — within a container, the key modules/classes and their

dependencies. Only draw the ones touched by the decision.

Use ASCII or Mermaid in the ADR. Keep diagrams legible in plain text.

Deep modules heuristic (Ousterhout)

A module's value is its interface relative to its implementation.

• Deep module: small interface, hides significant complexity. Good.
• Shallow module: interface as complex as the implementation. Bad — it

adds indirection without abstraction. Merge or deepen it.

When designing a new class or boundary, ask: is the interface materially smaller than the implementation? If not, redesign or merge.

Interface-design checklist

Before committing a new public interface (a class API, a backend function, a URL, a DB schema):

• [ ] Hides a decision that could change.
• [ ] Interface is the smallest expression of the capability.
• [ ] Does not leak internals (types, error shapes, ordering, state).
• [ ] Errors are part of the interface — documented, typed, narrow.
• [ ] One responsibility; if you describe it with "and", split it.
• [ ] Testable at the boundary if it touches the outside world (see the

tdd skill's boundary-mocking discipline and the active adapter's mocking guide, if one exists).

• [ ] Named using the project's ubiquitous language (see CONTEXT.md).

Cross-refs

• adr skill — format and status transitions.
• packages/prism-core/docs/design.md — RFC template and when a design doc

is required.

• tdd skill — boundary-interface and mocking discipline.
• domain-context skill — read CONTEXT.md before designing.