Full system architecture

/0.1 At-a-glance

Six numbers that define the platform shape

The platform is a Go-on-Postgres core banking system with a multi-tenant React SPA in front and an event-driven listener service behind. The numbers below are evidence-based from the live source tree at the cut-off date — every component referenced in the sections that follow is indexed under one of them.

/0.2 Stack signature

Eight runtime anchors

The technology stack is deliberately narrow. One language for all backend services (Go), one database for all authoritative state (PostgreSQL), one orchestrator (Kubernetes on EKS), one cloud (AWS). Every component below is in production use; nothing is research-stage.

/0.3 Surfaces & gateway

Customer-side, operator-side, and the edge between them

Two SPAs (customer + admin) sit in front of one API gateway. The gateway authenticates, authorises, rate-limits, and tenant-routes every request before any module sees it. There is exactly one surface for the platform and exactly one gateway — multi-tenant routing is internal, never per-tenant deployment.

Client tier

Gateway tier

Client ↔ gateway transports — HTTPS REST / JSON, Server-Sent Events, JWT bearer auth.

/0.4 Core API modules

Eight functional clusters · 45+ Go modules

The Go API is structured as functional clusters — each cluster a directory under corebanq.api/ with its own subpackages, GORM models, and DSL hooks where applicable. The double-entry ledger sits at the centre; every other cluster integrates with it via the outbox pattern (see /0.8) so no module owns its own settlement.

# OWT — outward wire transfer
rule "OWT" {
  when case {
    tariff   { type: "exchange" }
    gl-batch { txn = id
      book ledger = "22011" op = debit
    }
    call  { interface: "kyt_service" }
    route { event: "complete" }
  }
}

/0.5 Internal connectors

Fourteen single-purpose adapters

Every external runtime concern (a database, a queue, an SMS gateway, an LLM endpoint) sits behind a single-purpose adapter under corebanq.api/connectors/. Modules consume adapters by interface; the adapter is the only place that knows the wire format. Adapter-swapping is a configuration change, not a refactor.

/0.6 Storage & runtime

Eight services on the production runtime

Production runs on Kubernetes (EKS, eu-central-2). Development runs on Docker Compose with the same service list, minus AWS-managed substitutions. PostgreSQL is the source of truth for every record; Redis carries ephemeral state only; RabbitMQ is the reliable-messaging bus that connects the API to the listener service.

/0.7 Cloud & external

AWS-managed core, narrow third-party perimeter

The cloud surface is small and named — eight AWS services plus a third-party integration list grouped by control category. Every external integration sits behind one of the internal connectors in /0.5 — there is no direct external call from a module.

AWS managed services

Third-party integrations

/0.8 Transaction lifecycle

Outward wire transfer — DSL-driven state machine

Transactions are not implemented as ad-hoc Go code. They are declared as DSL rules — OWT_1.0.0.dsl, IWT_1.0.0.dsl, OWN_1.0.0.dsl — interpreted by the rule engine. The diagram below is the actual state machine for an outward wire, not a stylised summary. Every node is a step the engine takes; every transition is auditable.

Reliable messaging — outbox pattern

Side effects never block the API. Each module writes the side-effect intent into a Postgres outbox row in the same transaction as the state change. A poller fans the outbox into RabbitMQ; corebanq.listener consumes from RabbitMQ and delivers webhooks, runs TOTP workflows, and persists Redis state. If the listener stalls, the API does not.

Outbox events — customer_created, signatory_verified, signatory_forms_uploaded, signatory_accepted, document_signed.

/0.9 Data model

Twelve principal entities behind the API

The Postgres schema is normalised around twelve principal entity groups. GORM models map 1:1 to the API response shapes; there is no service-side aggregation layer that could drift from the database.