Architecture¶
Foundations¶
- Architectural principles — nine foundational principles (AP-001 through AP-009)
- AP-010: Modular by design — bounded ownership, explicit contracts, domain data products
- Environments and deployment — environment topology, CI/CD pipelines, IaC, test gates, branch strategy
- AI strategy — four modes of AI use, regulatory context, links to DT-009 and DT-011
- Architectural perspectives — thirteen evaluation lenses for assessing solutions and ADRs
- Architectural viewpoints — stakeholder communication framework; how to produce and use viewpoints
Platform topic pages¶
- Platform overview — layer summary, transaction path, analytics path, key constraints
- Data architecture — OLTP/OLAP/streaming, write-back pattern, data residency
- Frontend architecture — single codebase, mode resolution, security boundary
- Security architecture — zero trust, IAM, PAM, secrets, audit trail
Integration, contracts, and data models¶
These artefacts live in the Design section under System design:
- Event catalogue — all EventBridge domain events across 8 buses
- Interface contracts — synchronous module-to-module Lambda invocation shapes
- Data models — authoritative schema reference for all system domains
Architecture Decision Records¶
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-001 | Postgres as the OLTP operational store | Accepted | 2026-04-10 |
| ADR-002 | Snowflake as the analytics and risk compute platform | Accepted | 2026-04-10 |
| ADR-003 | CDC pipeline — Neon Postgres to Snowflake via Firehose and Apache Iceberg | Accepted | 2026-04-10 |
| ADR-004 | Single frontend codebase for customer and back office | Accepted | 2026-04-10 |
| ADR-005 | Payments partner at launch — direct scheme membership deferred | Accepted | 2026-04-10 |
| ADR-006 | ERP at the periphery — statutory reporting only | Accepted | 2026-04-10 |
| ADR-007 | Frontend framework — React/Next.js with Capacitor | Superseded | 2026-04-10 |
| ADR-008 | Reconciliation and exception management | Accepted | 2026-04-10 |
| ADR-009 | Insights and data visualisation approach | Accepted | 2026-04-10 |
| ADR-010 | Financial crime and fraud detection platform | Accepted | 2026-04-10 |
| ADR-011 | CRM approach — embedded in front end or external platform | Accepted | 2026-04-10 |
| ADR-012 | External disclosures system | Accepted | 2026-04-10 |
| ADR-013 | External data sharing from Snowflake | Accepted | 2026-04-10 |
| ADR-014 | Deposit and lending product set — launch sequencing | Accepted | 2026-04-10 |
| ADR-015 | Cross-border NZ/AU wallet and transfer design | Accepted | 2026-04-10 |
| ADR-016 | Transaction history design — data model, enrichment, and UX | Accepted | 2026-04-10 |
| ADR-017 | Transaction categorisation and merchant enrichment — in-house ML vs external API | Accepted | 2026-04-10 |
| ADR-018 | KYC and digital onboarding architecture | Accepted | 2026-04-10 |
| ADR-019 | Intelligent customer home screen and financial intelligence layer | Accepted | 2026-04-10 |
| ADR-020 | Customer financial automation rules engine | Accepted | 2026-04-10 |
| ADR-021 | Call recording, transcription, and CRM attachment | Accepted | 2026-04-10 |
| ADR-022 | CI/CD and deployment strategy | Accepted | 2026-04-10 |
| ADR-023 | Cloud provider and region strategy | Accepted | 2026-04-10 |
| ADR-024 | Database hosting — Neon serverless Postgres | Superseded | 2026-04-10 |
| ADR-025 | API layer — HTTP API Gateway and SST | Accepted | 2026-04-10 |
| ADR-026 | Customer authentication — Cognito, mobile-first, passwordless | Accepted | 2026-04-10 |
| ADR-027 | Internal staff authentication — Cognito and corporate SSO | Accepted | 2026-04-10 |
| ADR-028 | Document storage — S3 and Postgres metadata | Accepted | 2026-04-10 |
| ADR-029 | Domain event routing via Amazon EventBridge | Superseded | 2026-04-10 |
| ADR-030 | Secrets management — AWS Secrets Manager | Accepted | 2026-04-10 |
| ADR-031 | Observability — OpenTelemetry, CloudWatch, and X-Ray | Accepted | 2026-04-10 |
| ADR-032 | Customer notification service — Amazon Pinpoint | Accepted | 2026-04-10 |
| ADR-033 | Feature flag management — AWS AppConfig | Accepted | 2026-04-10 |
| ADR-034 | Web app hosting and mobile app distribution | Accepted | 2026-04-10 |
| ADR-035 | Snowflake account configuration and data residency | Superseded | 2026-04-10 |
| ADR-036 | Decision result publication — Snowflake to Neon | Accepted | 2026-04-10 |
| ADR-037 | Open Banking participation strategy — CDR, NZ API standard, and API monetisation | Accepted | 2026-04-10 |
| ADR-038 | Data access tier policy — Snowflake as the reporting and insight layer | Proposed | 2026-04-10 |
| ADR-039 | Market data sourcing — Snowflake Marketplace with provider abstraction | Accepted | 2026-04-10 |
| ADR-040 | SaaS usage metering and multi-tenant cost attribution | Accepted | 2026-04-15 |
| ADR-041 | Akahu as NZ external asset aggregation layer; direct APIs for AU super | Accepted | 2026-04-15 |
| ADR-042 | Single-stack deployment with jurisdiction as runtime context | Accepted | 2026-04-15 |
| ADR-043 | Standardised repository and module directory layout | Accepted | 2026-04-24 |
| ADR-044 | External provider stub strategy for dev and UAT environments | Accepted | 2026-04-27 |
| ADR-045 | Test data and environment fidelity strategy | Accepted | 2026-04-27 |
| ADR-046 | SD06 data product architecture — Snowflake-native orchestration, dbt transformation layer, schema-as-product | Accepted | 2026-05-01 |
| ADR-047 | Snowflake reference data write-back — dedicated Lambda pattern for operational delivery | Accepted | 2026-05-01 |
| ADR-048 | Database-enforced invariants — Postgres constraints and triggers as a first-class defence layer | Accepted | 2026-05-01 |
| ADR-049 | Snowflake-native compute — Alerts and DMFs preferred over Lambda monitors within SD06 | Accepted | 2026-05-01 |
| ADR-050 | SD06 test layering — dbt unit tests for SQL behaviour, Vitest policy tests for SQL structure | Accepted | 2026-05-01 |
| ADR-051 | EventBridge bus naming — hyphen-separated names matching repo pattern | Accepted | 2026-05-01 |
| ADR-052 | Neon database naming — bank_ prefix with snake_case domain abbreviation | Superseded | 2026-05-01 |
| ADR-053 | Build artefact versioning and stage promotion model | Accepted | 2026-05-02 |
| ADR-054 | Snowflake DDL management via DCM Projects | Accepted | 2026-05-02 |
| ADR-055 | SD06 test layering — dbt unit tests for SQL behaviour, Vitest policy tests for SQL structure | Proposed | 2026-05-04 |
| ADR-056 | Snowflake-native dbt Projects for SD06 model execution | Accepted | 2026-05-07 |
| ADR-057 | React ecosystem — Vite, TanStack Router, TanStack Query, Tailwind CSS, Radix UI | Accepted | 2026-05-08 |
| ADR-058 | Credit card platform boundary — in-platform vs external capability assignment | Accepted | 2026-05-08 |
| ADR-059 | Maker-checker as a platform-wide workflow primitive | Accepted | 2026-05-09 |
| ADR-060 | Tenant extension fields — runtime-extensible custom entity attributes | Proposed | 2026-05-09 |
| ADR-061 | COB partitioning for portfolio-scale batch processing | Accepted | 2026-05-09 |
| ADR-062 | Contract directory convention and minimal-cascade deployment | Accepted | 2026-05-13 |
| ADR-063 | GitLab Package Registry for versioned cross-repo contract packages | Accepted | 2026-05-13 |
| ADR-064 | Consolidated Neon database — schema-per-domain isolation | Accepted | 2026-05-15 |
| ADR-065 | Cognito custom claims as session state carrier | Accepted | 2026-05-15 |
| ADR-066 | Postgres-backed idempotency store via Powertools BasePersistenceLayer | Accepted | 2026-05-17 |
| ADR-067 | SD06 regulatory dashboard rendering — Recharts and independent Streamlit per module | Proposed | 2026-05-21 |
See also: Customer, party and user schema — the canonical party-and-relationship data model: parties, operating contexts, user access, DCS/AML/CRS views, and the sole trader / property investor / multi-entity design.
See also: Module-to-epic mapping — engineering backlog derived from the systems register.