Creating a Design Module

A design document explains how a feature or subsystem is built — its data model, the way it processes information, and the contracts it exposes. It sits between requirements (what the system must do) and architecture (why the system is shaped the way it is), and it is the durable reference a developer reads before implementing or changing the feature.

1. When to use this type

Create a Design module (often named design or common-design for cross-cutting designs) when features need a stable, implementation-oriented reference that outlives any one work item: schemas, processing models, state machines, shared patterns.

It IS design when… It is NOT design when…

It describes how a feature is built (model, flow, contracts)

It states what must be true → Requirements

It is durable — reflects the current intended build

It records a decision and its trade-offs → ADR

A developer reads it to implement/change the feature

It is the running exploration of a problem → a design journal

Keep durable design separate from deferred/aspirational design. A model that is in production is one document; an automation layer planned for later is another that builds on it. Conflating them makes the reader unsure what exists today. (EMS splits its leaderboard model from the deferred sync layer for exactly this reason.)

2. Standard structure

modules/design/                  # or common-design for cross-cutting
├── nav.adoc
└── pages/
    ├── index.adoc               # Catalogue grouped by subsystem / concern
    ├── <subsystem>/
    │   ├── <model>.adoc         # The durable model (schema + processing)
    │   └── <extension>.adoc     # A layer that builds on the model
    └── <shared-pattern>.adoc    # Cross-cutting patterns reused across features

3. Page template

A design page typically covers: overview & boundaries, the model/schema, the processing (how data flows / is classified / transitions), contracts (APIs, events), and related work. Copy templates/design-template.adoc, or:

= <Subsystem / Feature> Design
:description: <one line — the durable model this describes>

== Overview
<What this designs; explicitly what it is SEPARATE from (related designs, deferred layers).>

== Model / Schema
<Entities, fields, relationships — grounded in the actual code/schema.>

== Processing
<How information flows, is classified, or transitions — the behaviour the model enables.>

== Contracts
<APIs, events, extension points the feature exposes.>

== Related
<The requirement it fulfils, ADRs that shaped it, procedures that operate it.>

Ground design in the actual schema and code, not a paraphrase of an earlier plan. A design doc that describes entities that diverged from what shipped is worse than none. Verify against the codebase and link to it.

4. Flexibility

  • Small feature: one page (model + processing together).

  • Cross-cutting concern: a common-design subfolder with a model page plus pages for each extension that builds on it.

  • Heavily evolving area: pair the durable design page with a design journal entry for the running exploration; promote settled decisions into the design page and ADRs.

5. Quality checklist

  • States what it designs and what it is separate from.

  • Model is grounded in the real schema/code (verified, linked).

  • Durable model is not tangled with deferred/aspirational layers.

  • Cross-links to the requirement (what) and ADRs (why).

  • Procedures/operations that operate the feature link back here.

6. Common pitfalls

  • Paraphrased schema — drifts from the code; ground and link instead.

  • Durable + deferred mixed — readers can’t tell what exists; split them.

  • Design that’s really a decision log — if it’s about why and trade-offs, it’s an ADR.

  • Restating requirements — link to them; design is about how.

7. Related