Wiki methodology¶

This page explains how the wiki is structured, how knowledge flows through it, and how every artefact — from a regulation to a line of code — traces back to an accountable entity.

It is written for two audiences: engineers and architects who need to understand where things live and why; and AI agents that need a precise model of how to read the wiki, what questions to ask it, and what artefacts to produce.

The traceability chain¶

Regulations ──────────────────────────────────────────────────────────────────────────┐
  │  define obligations                                                                 │
  ▼                                                                                     │
Risk Domains ─── own ──► Policies ─── generate ──────────────────────────────────────┐│
                                                                                       ││
Business Goals ─── enable ──► Capabilities ─── decompose into ──► Functional          ││
                                                                   Requirements ───────┼┼──► Modules
                                                                                       ││       │
System Goals ──────────── define ──► NFRs (non-functional ────────────────────────────┘│       │
                                          thresholds)                                   │       │
                                                                                        │       │
                                          Policies ───────────────────────────────────┘        │
                                          (satisfied by modules                                 │
                                           in GATE/AUTO/CALC/ALERT/LOG modes)                  │
                                                                                                ▼
                                                                               Design artefacts → Code

Three independent threads converge on modules:

Thread	Chain	Notes
Business	Business Goals → Capabilities → FRs → Modules	What the bank wants to do commercially
Compliance	Regulations → Risk Domains → Policies → FRs → Modules	What the bank is obliged to do legally
Non-functional	System Goals → NFRs → Modules	Cross-cutting quality thresholds; not per-module, per-platform

NFRs are primarily system-wide constraints (latency, availability, throughput, data residency). They do not originate from business goals, though a small number overlap (e.g. NFR-001 uptime supports BG-001 customer trust).

Entity types and their roles¶

Business goals (`BG-NNN`)¶

High-level commercial outcomes the bank is building toward. Examples: acquire customers, achieve revenue target, become the financial OS for sole traders. Business goals are authored by executives; they do not change frequently.

→ Each business goal is supported by one or more Capabilities.

Capabilities (`CAP-NNN`)¶

Discrete user-facing or system-facing things the bank can do. Capabilities are the unit of commercial scope. Each capability is named as a concrete ability: "Pay a NZD bill via internet banking", "Detect a structuring pattern in customer transactions".

→ Each capability is satisfied by one or more FRs and delivered by one or more Modules.

Functional requirements (`FR-NNN`)¶

Precise, testable statements of what the system shall do. Format: "System shall [observable behaviour]." Every FR is owned by exactly one module. Every FR has corresponding acceptance criteria expressed as automated tests.

→ FRs are the direct input to module implementation and the basis of the test suite.

Non-functional requirements (`NFR-NNN`)¶

Measurable thresholds that all applicable modules must meet. Format: "[Metric] shall not exceed / shall achieve [threshold]." NFRs apply to classes of modules (all real-time handlers, all batch processors) rather than to individual FRs.

→ NFRs feed into the NFR column of a module's execution plan, and into load/stress test design.

Regulations¶

External legal instruments (NZ AML/CFT Act, AU AML/CTF Act, Deposit Takers Act 2023, etc.). Not authored internally — summarised with the clauses that generate obligations.

→ Regulations generate policies via risk domains.

Risk domains (`D0N`)¶

Governance groupings that own a family of policies. Each risk domain has an owner (typically a C-level or Head-of). Examples: AML / Financial Crime (D03), Credit Risk (D06), Prudential Capital (D09).

→ Risk domains group and own policies.

Policies (`CODE-NNN`)¶

Internal control instruments derived from regulations. Each policy specifies what the bank must do to satisfy a legal obligation and how modules satisfy it. The satisfaction mode describes how a module contributes:

Mode	Meaning
GATE	Module enforces the policy as a hard gate — the flow cannot proceed without it
AUTO	Module automates a required process without human intervention
CALC	Module computes a value required by the policy (e.g. a risk score)
ALERT	Module generates a notification or alert when a policy threshold is crossed
LOG	Module maintains an audit trail required by the policy

Modules (`MOD-NNN`)¶

The unit of implementation. Each module maps to a bounded Lambda-based service within a system domain. A module owns its schema tables, satisfies a specific list of FRs and policies, and produces a defined set of design artefacts.

→ Modules are the leaf nodes of the traceability chain — everything above is context and constraint; modules are where code is written.

System domains (`SD0N`)¶

Modules are grouped into system domains. Each system domain: - Owns a Postgres schema (SD01–SD05, SD08) or a Snowflake database (SD06–SD07) - Has a dedicated EventBridge bus (bank-[domain]) - Maps to a single code repository (bank-core, bank-kyc, etc.) - Aligns to one or more business domains

Cross-domain reads go through the owning domain's API — never direct DB cross-connect.

How design artefacts connect¶

When a module is ready to be implemented, the traceability chain becomes the build chain:

Module YAML (FR list, policy list, capability list)
  │
  ▼
Execution plan          ← Human or AI orchestrator writes this first
  │  inputs: FR list, NFR thresholds, interface contracts, data model
  │
  ▼
Technical design        ← AI coding agent or engineer produces this
  │  covers: internal architecture, key decisions, security, performance
  │
  ▼
Implementation          ← Code, tests, config, fixtures
  │  guided by: execution plan + technical design
  │
  ▼
Drift report            ← AI coding agent writes post-implementation
     captures: deviations, new FRs discovered, schema changes
     output: *.handoff.md files → wiki update

The drift report closes the loop. Any deviation from the execution plan, any new FR discovered, or any schema change not in the system data model generates a handoff file that is processed back into this wiki.

See Module design for the full artefact specification and templates.

How to read this wiki (for AI agents)¶

When assigned to implement a module, read in this order:

Module YAML + MD from /systems/SD0x-*/MOD-xxx-*.md — what the module must do and which FRs/policies it satisfies
FR register (/goals/fr-register/) — the exact acceptance criteria for each FR in scope
NFR register (/goals/nfr-register/) — the thresholds that apply to this module's class
Data model for the module's system domain (/design/system/data-models/) — exact table and column names; do not deviate
Interface contracts (/design/system/interface-contracts/) — the exact Lambda invocation shapes for modules this one calls or that call it
Event catalogue (/design/system/event-catalogue/) — the exact event schemas for events this module emits or consumes
Module design template (/design/module/template/) — what artefacts you must produce (execution plan, technical design, drift report, etc.)
Test strategy (/design/test-strategy/) — what test coverage is required and how CI gates enforce it

When writing content back to the wiki (via handoff), use the schema definitions in scripts/schema.py and the entity format from CLAUDE.md.

AI context URLs¶

For AI tools that cannot follow links, single-page full-content snapshots are available:

Section	URL
Entity index (IDs + titles)	`https://bank-wiki.pages.dev/ai-context/index/`
Policies	`https://bank-wiki.pages.dev/ai-context/policies/`
Systems & modules	`https://bank-wiki.pages.dev/ai-context/systems/`
Risk domains	`https://bank-wiki.pages.dev/ai-context/risk-domains/`
Business domains	`https://bank-wiki.pages.dev/ai-context/business-domains/`
Products	`https://bank-wiki.pages.dev/ai-context/products/`
Architecture	`https://bank-wiki.pages.dev/ai-context/architecture/`
Goals	`https://bank-wiki.pages.dev/ai-context/goals/`

These snapshots are regenerated on every wiki compile and contain no broken links — they are the preferred entry point for AI context loading.

What this wiki is not¶

Not a code repository. No .py, .js, .ts, .sql files (except scripts/ which contains the build tooling for this repo only).
Not speculative. Every entity has an owner and, where applicable, a review date.
Not meeting notes. Structured reference material only — decisions recorded as ADRs, obligations as policies, requirements as FRs.
Not a project management tool. Module build_status is updated by CI, not by hand.

Wiki methodology¶

The traceability chain¶

Entity types and their roles¶

Business goals (BG-NNN)¶

Capabilities (CAP-NNN)¶

Functional requirements (FR-NNN)¶

Non-functional requirements (NFR-NNN)¶