Skip to content

Module design

Module-level design artefacts are produced in each module's code repository under docs/design/MOD-NNN.md and are archived to this wiki via handoff processing. The module design index shows all archived design docs. This page defines the framework — what artefacts are required, what they contain, and how they flow here.

The module design lifecycle

Wiki (MOD-xxx YAML + MD)
  │  defines: capabilities, requirements, policies_satisfied
  │
  ▼
Pre-AI execution plan          ← Written before any code is generated
  │  input: FR list, NFR list, contracts, data model
  │
  ▼
Technical design               ← Produced by AI agent or engineer
  │  covers: architecture within the module, key decisions
  │
  ▼
Implementation                 ← Code, tests, config
  │  produces: APIs, fixtures, module data model (if non-standard)
  │
  ▼
Drift report + handoff         ← Fed back to this wiki via handoff mechanism
     covers: deviations, new FRs discovered, schema changes

Required artefacts per module

Each module repository must contain a /docs/ directory with the following structure:

/docs/
  technical-design.md          ← Architecture decisions within the module
  data-model.md                ← Module-specific tables / any deviation from system model
  contracts.md                 ← Module's specific API contracts and event schemas
  api.md                       ← OpenAPI spec summary or link to spec file
  fixtures.md                  ← Seed data: enums, lookup values, test records
  config.md                    ← Environment variables, feature flags, secrets (names only)
  execution-plan.md            ← Pre-AI plan: scope, steps, acceptance criteria by FR
  drift-report.md              ← Post-implementation: deviations, new discoveries

See the module design template for the canonical content structure of each artefact.

Artefact descriptions

technical-design.md

The architectural decisions made within the module scope — not global ADRs, but the module-level choices: - Internal component structure - Key algorithms or processing logic - Third-party dependencies and why chosen - Security and data handling decisions - Performance approach (caching, batching, async)

Source: Produced by the AI agent before implementation begins, reviewed by the tech lead. Must reference the module's FR list explicitly.

data-model.md

Module-specific database objects. In most cases this is empty or points to the system data model — only populated when the module introduces tables not in the system-level data model, or has a more detailed view of a subset of tables.

Source: Generated from implementation; fed back to the system data model page via handoff if new tables are introduced.

contracts.md

The module's specific slice of the interface contracts — the exact request/response shapes for Lambda invocations this module makes or receives, and the exact event schemas for events this module emits or consumes.

Source: Derived from the system-level contracts; extended if the module introduces new interactions.

api.md

Summary of external-facing API endpoints (if any). References the OpenAPI spec file in the repo. Includes: endpoint, method, auth requirement, rate limit, input schema, output schema, error codes.

Source: Auto-generated from the OpenAPI spec or hand-authored.

fixtures.md

Seed data required for the module to operate in a non-production environment: - Enum values and lookup tables - Test customer records (anonymised) - Reference data (e.g. currency codes, MCC codes) - Feature flag defaults

Source: Maintained by the engineering team; used by CI to populate test environments.

config.md

All environment variables and AWS Secrets Manager secret names the module requires. Values are never recorded here — only names, descriptions, and whether required or optional.

Format: 

| Variable | Type | Required | Description |
|---|---|---|---|
| DB_HOST | env | Yes | Neon Postgres connection host |
| KYC_API_KEY | secret | Yes | SM path: /prod/kyc/api-key |

execution-plan.md

Written before the AI agent begins implementation. Defines the exact scope and acceptance criteria for the current implementation sprint or PR.

Structure (see template): - Objective and scope (1 paragraph) - FR list being implemented (by FR ID — do not restate the requirement) - NFR thresholds that apply - Implementation steps (ordered list) - Files to create or modify - External dependencies (other modules or APIs needed) - Test requirements (by test type) - Definition of done

Source: Written by the AI orchestrator or tech lead before handing off to the coding agent.

drift-report.md

Written after implementation, before the PR is merged. Captures deviations from the execution plan and any new discoveries.

Structure: - Summary (implemented as planned / deviated) - Deviations from execution plan (each with reason) - New FRs or NFRs discovered (candidates for wiki handoff) - Schema changes vs system data model (candidates for wiki handoff) - Open questions requiring human decision - Handoff items (formatted as wiki handoff references)

Any drift report that identifies new entities, schema changes, or new requirements must generate a *.handoff.md file to update the wiki. This closes the feedback loop between code and wiki.

How design docs reach this wiki

When an AI agent completes a module it produces docs/design/MOD-NNN.md in the code repo. The wiki orchestrator processes this during handoff:

  1. cp ../[repo]/docs/design/MOD-NNN.md source/pages/design/modules/MOD-NNN.md
  2. python3 scripts/compile.py — the compiler auto-discovers source/pages/design/modules/MOD-*.md and includes them in both the wiki NAV and the AI context design/ aggregation page

Once archived, the design doc is visible: - In the wiki under Design → Module design → MOD-NNN - In the AI context URL https://bank-wiki.pages.dev/ai-context/design/ — fetched by all Claude Code agents at session startup

Handoff files — drift reports that introduce new wiki entities (new tables, new FRs, new capabilities) continue to create *.handoff.md files that the wiki processes separately.

CI hooks — the update-wiki.sh script in each code repo writes code_commit and build_status: Built back to the module YAML.