Module design template¶
Copy this template into a module's /docs/ directory and populate each section. Sections marked [AI-generated] are produced by the coding agent; [human-reviewed] require sign-off before the PR merges; [auto-generated] are produced by tooling.
technical-design.md¶
# Technical design — [MOD-xxx] [Module name]
**Module:** [MOD-xxx](link-to-wiki)
**System:** [SD0x system name](link-to-wiki)
**Repo:** [repo-name]
**FR scope:** FR-xxx, FR-xxx, FR-xxx
**Author:** [AI agent | engineer name]
**Date:** YYYY-MM-DD
## Objective
One paragraph: what this module does and why it exists.
Reference the capability it satisfies: [CAP-xxx](link).
## Internal architecture
Describe the component structure within the module boundary:
- Lambda handler(s) and their responsibilities
- Internal service classes or utilities
- Data access layer approach
- Async vs sync processing decisions
## Key design decisions
For each non-obvious decision made within the module:
### Decision: [title]
**Context:** Why this was a decision point.
**Options considered:** A, B, C.
**Choice:** B.
**Reason:** ...
**Trade-offs:** ...
## External dependencies
List every external call this module makes:
- Module-to-module: [MOD-yyy] via Lambda invoke — see contracts.md
- Database: [schema.table] — read / write / read-write
- EventBridge: emits [event-name] on [bus-name]
- External APIs: [name, purpose]
## Security and data handling
- PII fields handled: [list]
- Encryption at rest: [yes/no, how]
- Encryption in transit: [yes/no, how]
- Secrets used: see config.md
## Performance approach
- Expected p99 latency target: [from NFR register]
- Caching strategy (if any)
- Batching or async processing (if any)
- Expected throughput at scale
## Test approach
Brief summary — full test requirements in execution-plan.md.
execution-plan.md¶
# Execution plan — [MOD-xxx] [Module name]
**Sprint / PR:** [reference]
**Date:** YYYY-MM-DD
**Author:** [AI orchestrator | tech lead]
**Status:** Draft | Approved | In progress | Complete
## Objective
One paragraph describing exactly what this implementation sprint will deliver.
Do not restate requirements — reference them by FR ID.
## Scope
### Functional requirements in scope
[FR-xxx], [FR-xxx], [FR-xxx]
Fetch from: https://bank-wiki.pages.dev/goals/fr-register/
### NFR thresholds applying to this module
[NFR-xxx] — [threshold]
[NFR-xxx] — [threshold]
Fetch from: https://bank-wiki.pages.dev/goals/nfr-register/
### Out of scope (deferred)
[FR-xxx] — deferred to [reason]
## Implementation steps
1. Create schema migration: `[schema].[table]`
2. Implement Lambda handler: `src/handlers/[name].ts`
3. Implement service layer: `src/services/[name].ts`
4. Write unit tests: `src/handlers/[name].test.ts`
5. Write contract tests: `src/__tests__/contracts/[name].test.ts`
6. Add fixtures: `src/fixtures/[name].ts`
7. Update config: `.env.example`, `src/config.ts`
8. Write integration test: `src/__tests__/integration/[name].test.ts`
## Files to create or modify
| File | Action | Notes |
|---|---|---|
| `src/handlers/xxx.ts` | CREATE | Lambda handler |
| `src/services/xxx.ts` | CREATE | Business logic |
| `migrations/xxx.sql` | CREATE | Schema migration |
| `src/__tests__/xxx.test.ts` | CREATE | Unit tests |
## External dependencies
| Dependency | Type | Required before this work |
|---|---|---|
| [MOD-yyy name] | Lambda invoke | Yes — must be deployed |
| `schema.table` | Database read | Schema migration must run |
## Test requirements
| Test type | Coverage target | Notes |
|---|---|---|
| Unit | 100% of FR acceptance criteria | One test per FR clause |
| Contract | All event schemas, all invoke shapes | Schema validation |
| Integration | Happy path + key failure paths | Against real downstream |
| NFR | p99 latency, availability | Load test in staging |
## Definition of done
- [ ] All FR-xxx acceptance criteria pass as automated tests
- [ ] NFR thresholds verified in staging
- [ ] Contract tests pass against live downstream modules
- [ ] No unresolved security findings
- [ ] Drift report written and reviewed
- [ ] Handoff file created for any wiki deviations
- [ ] PR approved by tech lead
drift-report.md¶
# Drift report — [MOD-xxx] [Module name]
**Sprint / PR:** [reference]
**Date:** YYYY-MM-DD
**Author:** [AI agent | engineer name]
**Execution plan:** [link]
## Summary
[ ] Implemented as planned — no material deviations
[x] Deviated from plan — see deviations below
## Deviations from execution plan
### Deviation 1: [title]
**What changed:** ...
**Reason:** ...
**Impact:** Functional / NFR / Schema / None
**Handoff required:** Yes / No
## New discoveries
### New FRs identified
List any functional requirements discovered during implementation that are not in the
FR register. For each:
- Description (as a requirement statement: "System shall...")
- Suggested FR ID (next available)
- Module it applies to
- **Action:** create handoff file `new-fr-[module].handoff.md`
### Schema changes
List any tables or columns added/changed vs the system data model.
- **Action:** create handoff file `schema-[sdxx]-[table].handoff.md`
### New capabilities identified
List any capabilities discovered that are not in the CAP register.
- **Action:** create handoff file `new-cap.handoff.md`
## Open questions (requires human decision)
List anything that could not be resolved without human input.
| Question | Impact | Deadline |
|---|---|---|
| ... | ... | ... |
## Handoff files generated
List all *.handoff.md files created as a result of this drift report.
| File | Type | Entity |
|---|---|---|
| `new-fr-mod-xxx.handoff.md` | new FR | MOD-xxx |
fixtures.md¶
# Fixtures — [MOD-xxx] [Module name]
Seed data required for this module to operate in dev/test environments.
Values here are **not** production data — use clearly fictional/test values.
## Enum and lookup values
### [table_name].[column_name]
| Value | Description |
|---|---|
| VALUE_A | ... |
| VALUE_B | ... |
## Reference data
### [description]
```sql
INSERT INTO [schema].[table] (col1, col2) VALUES
('val1', 'val2'),
('val3', 'val4');
Test customer records¶
Test records must use clearly fictional data (not real names, addresses, or IRD/TFN numbers).