ration/docs/ARCHITECTURE.md
caelum0x 521d6176c4 feat(ration): REST/JSON facade over gateway, final phase-2 doc updates
Phase 2 section 7 (the other half, alongside sdk/go/ration and
sdk/rust/ration-client already pushed in c5297e4/8215fb8): a hand-rolled
internal/httpapi on services/gateway translating JSON <-> the gRPC source
of truth (cards, deposits, bridge funding, activity), documented as a
convenience facade over gRPC, not a parallel implementation. Also folds in
the remaining phase-2 doc updates (ARCHITECTURE/RUNBOOK/THREAT-MODEL/
AIRWALLEX-SETUP/SUBMISSION, ADR 0003/0004) and docker-compose/Makefile/
.env.example wiring from the resumed phase-2 workflow's final agents.

Verified: go build/vet/test clean across all 10 services + both new SDKs,
`make build && make test` clean end to end (C WAL, Rust ledger-core + the
new Rust SDK, every Go module including sdk/go/ration).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-19 12:56:58 +03:00

13 KiB

Architecture

Money type

Everywhere: fixed-point integer minor units (int64, e.g. cents) + ISO 4217 currency string. Never float. Mirrored as Money{minor_units, currency} in proto, ledger-core::money::Money in Rust (checked add/sub, no silent overflow), pkg/money.Money in Go.

services/wal (C)

A minimal, real write-ahead log — this is the low-level showcase piece, not a toy. Format: sequence of length-prefixed, CRC32-checksummed frames, append-only, fsync() after every durable append (durability > throughput for a ledger). On startup, replay from the last valid frame to rebuild state; a corrupt/truncated tail frame (torn write) is detected via CRC and discarded, not treated as fatal.

Files:

  • wal.h — public API: wal_open, wal_append, wal_read_next, wal_sync, wal_close, wal_recover.
  • wal.c — implementation.
  • crc32.c / crc32.h — standalone CRC32 (no external deps).
  • frame.h — on-disk frame layout (length, crc, payload) as a packed struct with explicit byte order (little-endian on disk, documented).
  • tests/test_wal.c — append/read-back, torn-write recovery, fsync-crash simulation (truncate mid-frame, assert recovery drops it cleanly).
  • Makefile — builds libwal.a (static lib) consumed by Rust via FFI, plus test_wal binary.
  • bench/bench_wal.c — append throughput micro-benchmark (optional but real, not a stub).

services/ledger-core (Rust)

Owns all tenant/deposit/balance/ledger-entry state. Links libwal.a via a build.rs that compiles services/wal with cc and a thin unsafe extern "C" binding module (src/wal_ffi.rs) wrapped in a safe Wal struct — no unsafe outside that one module.

Files:

  • Cargo.toml (deps: tonic, prost, tokio, rusqlite or sled for the queryable index — WAL is the durability source of truth, an embedded index db is fine for list/query paths), build.rs (compiles C, runs tonic-build on ../../proto/*.proto).
  • src/main.rs — boots the gRPC server (LedgerCore service from ledger.proto).
  • src/money.rs — Money type, checked arithmetic, currency mismatches are a typed error, not a panic.
  • src/wal_ffi.rs — the only unsafe module; safe wrapper around libwal.a.
  • src/ledger.rs — core domain: apply_entry (idempotent on idempotency_key, enforces reserve floor on DEBIT/HOLD before writing to WAL, THEN updates in-memory/indexed balance), get_balance, check_reserve_floor.
  • src/tenant.rs, src/deposit.rs, src/agent_decision.rs — domain entities + repository functions over the index db.
  • src/grpc.rs — LedgerCore trait impl, maps domain <-> proto types, recovers WAL state on boot before accepting RPCs.
  • src/error.rs — typed domain errors -> tonic::Status mapping.
  • tests/idempotency.rs, tests/reserve_floor.rs, tests/recovery.rs (kills the process mid-write via a test hook, restarts, asserts no lost or double-applied entries) — these are the tests that actually prove the ledger is correct; do not skip them.

services/gateway (Go) — thin BFF

Post section-1 split (docs/SCALE-EXPANSION.md section 1, docs/adr/0004): gateway no longer owns Airwallex, tenant CRUD or the rationing math directly — it is a thin BFF/aggregator implementing gateway.proto by fanning out gRPC calls to the four services below. Its external interface (what the TUI/CLI/agent dial) is byte-for-byte unchanged from before the split.

Files:

  • cmd/gateway/main.go — wiring: config, ledger-core client (for SimulateDeposit only), card-issuance client, webhook-ingestion client (relayed into the local activity bus), gRPC server for gateway.proto.
  • internal/config/config.go — env loading + validation: where to dial each backing service, rate-limit tuning, mTLS. No Airwallex or bridge-policy config anymore (moved to card-issuance).
  • internal/cardissuanceclient/client.go — typed gRPC client wrapper around cardissuance.CardIssuanceClient.
  • internal/webhookeventsclient/client.go — typed gRPC client wrapper that subscribes to webhook-ingestion's StreamEvents and republishes every event onto gateway's own internal/activity bus.
  • internal/ledgerclient/client.go — typed gRPC client wrapper around ledger.LedgerCoreClient, used only by SimulateDeposit now.
  • internal/activity/stream.go — fan-out event bus (Go channels) feeding StreamActivity gRPC stream to the TUI — fed both by gateway's own RPC handlers (card/bridge/deposit events) and by the webhook-ingestion relay above.
  • internal/grpcserver/server.go — gateway.proto service impl: each method either translates to a cardissuanceclient call (IssueCard, AdjustCardLimit, GetCard, ListCards, RationBridgeFunding), talks to ledger-core directly (SimulateDeposit), or serves the local activity bus (StreamActivity).
  • internal/ratelimit/limiter.go — per-tenant token bucket in front of every RPC on this service's public gRPC surface (unchanged by the split — this is gateway's surface to protect, not any backing service's).
  • go.mod, *_test.go next to each package.

services/auth (Go)

New capability, not an extraction (docs/adr/0004) — nothing in the pre-split gateway issued per-service mTLS certs or tenant API keys/JWTs. Has no ledger-core dependency.

Files:

  • cmd/auth/main.go — wiring: JWT signing key, CA (fresh in-memory or loaded from disk), gRPC server for auth.proto.
  • internal/apikey/apikey.go — tenant API-key issuance (plaintext secret returned once), salted-hash verification, revocation.
  • internal/jwtauth/jwtauth.go — short-lived bearer-token minting and verification, scoped to a tenant + subject.
  • internal/servicecertca/ca.go — runtime CSR signing against an in-process CA, for service-to-service mTLS identity issuance.
  • internal/grpcserver/server.go — auth.proto service impl, wires the above. Not yet dialed by gateway or any other service — see docs/THREAT-MODEL.md's known-gap 1.

services/tenant-registry (Go)

A direct extraction of the old gateway's internal/tenant/service.go (docs/adr/0004) — owns no state of its own, every write proxies to ledger-core.

Files:

  • cmd/tenant-registry/main.go — wiring: ledger-core client, gRPC server for tenant_registry.proto.
  • internal/tenant/service.go — CreateTenant/GetTenant/ListTenants, delegates persistence to ledger-core.
  • internal/ledgerclient/client.go — this service's own typed gRPC client wrapper around ledger.LedgerCoreClient (each split service gets its own copy, not a shared import — see docs/adr/0004).
  • internal/grpcserver/server.go — tenant_registry.proto service impl.

services/card-issuance (Go) — the highest-value service

A direct extraction of the old gateway's internal/card + internal/bridge (docs/adr/0004): Airwallex issuing calls and the rationing/bridge-funding math — where real money decisions happen. Stateless and idempotent per tenant (correctness rests on ledger-core's own idempotent, reserve-floor-checked ApplyEntry), so it is safe to run as N replicas.

Files:

  • cmd/card-issuance/main.go — wiring: config, ledger-core client, Airwallex client (mock or live per AIRWALLEX_MODE), gRPC server for card_issuance.proto.
  • internal/config/config.go — Airwallex + bridge-policy env loading (this service's share of the old gateway's internal/config).
  • internal/airwallex/client.go / live.go / mock.go — unchanged from the old gateway's package of the same name, moved verbatim.
  • internal/cardsvc/service.go — IssueCard, AdjustCardLimit, GetCard, ListCards: airwallex call -> ledgerclient reserve-floor check -> persist card metadata -> ledger entry for any hold.
  • internal/bridge/service.go — RationBridgeFunding: the actual rationing math (see AGENT-DESIGN.md's policy) — computes how much of a requested amount can be granted without breaching reserve floor, applies a HOLD ledger entry for the granted portion. Carries over the old gateway's bridge/service_test.go cases unchanged — the business logic didn't change, only which deployable it lives in.
  • internal/ledgerclient/client.go — this service's own typed gRPC client wrapper around ledger.LedgerCoreClient.
  • internal/grpcserver/server.go — card_issuance.proto service impl, a direct passthrough to cardsvc/bridge (unlike the old gateway, this package's wire types and its internal services' types are identical, so there's no translation to do here — gateway's own internal/grpcserver is where the cardissuance.* <-> gateway.* translation now happens).

services/webhook-ingestion (Go)

A direct extraction of the old gateway's internal/airwallex/webhook.go (signature verification) + internal/httpserver/webhooks.go (the HTTP listener) (docs/adr/0004) — isolates Airwallex's bursty, externally triggered webhook traffic from every other service's deploy cadence.

Files:

  • cmd/webhook-ingestion/main.go — wiring: ledger-core client, webhook secret, gRPC server for webhook_ingestion.proto and a plain HTTP listener for /webhooks/airwallex (always on, independent of any mock/live mode — unlike the old gateway's webhook listener, which only started in AIRWALLEX_MODE=live).
  • internal/airwallex/webhook.go — webhook payload types + HMAC signature verification, moved verbatim from the old gateway.
  • internal/webhookhandler/webhooks.go — the HTTP handler: verifies signature, parses the envelope, turns global_account.transaction.created into a MarkDepositReceived call against ledger-core, publishes a normalized event either way.
  • internal/eventbus/eventbus.go — fan-out event bus (Go channels) feeding webhook_ingestion.proto's StreamEvents RPC — the documented subscriber is gateway's own internal/webhookeventsclient, merging these events into its activity feed.
  • internal/ledgerclient/client.go — this service's own typed gRPC client wrapper around ledger.LedgerCoreClient.
  • internal/grpcserver/server.go — webhook_ingestion.proto service impl (StreamEvents only — webhook ingestion itself happens over plain HTTP, not gRPC).

services/agent (Go)

The actual "agentic" part. A loop, not a chatbot.

Files:

  • cmd/agent/main.go — polling loop: every N seconds, ask ledger-core for late deposits (ListLateDeposits), and for each tenant with pending card requests, run the decision pipeline.
  • internal/policy/rules.go — deterministic, auditable rules evaluated BEFORE any LLM call: hard reserve-floor floor, max single-grant cap, max grants per tenant per day. These can never be overridden by the LLM — the LLM only decides how much within the rule-approved envelope and what to tell the tenant, never whether to breach a hard rule.
  • internal/llm/provider.go — thin interface over an Anthropic Messages API client (model configurable via RATION_AGENT_MODEL, default claude-sonnet-5), tool-calling loop.
  • internal/llm/tools.go — tool schemas: ration_bridge_funding, issue_card, adjust_card_limit, notify_tenant — each tool's handler calls the gateway gRPC client, and every tool call + result is logged via ledgerclient.RecordAgentDecision for audit (never silent).
  • internal/llm/prompt.go — system prompt: the rationing policy in prose, explicit instruction to stay within the pre-computed hard envelope from policy/rules.go, and to prefer partial grants + clear tenant notification over silent decline.
  • internal/loop/runner.go — ties policy + llm + gateway client together, per-tenant decision cycle, structured logging of every decision.
  • go.mod, internal/policy/rules_test.go, internal/loop/runner_test.go (with a fake LLM provider so the loop is tested without network calls).

services/tui (Go, Bubble Tea)

Files:

  • cmd/tui/main.go — bubbletea program entry.
  • internal/model/model.go — top-level tea.Model, tab state (tenants / deposits / cards / activity feed).
  • internal/view/tenants.go, deposits.go, cards.go, activity.go — one file per tab, each a lipgloss-styled table/list.
  • internal/client/grpc.go — gateway + ledger-core gRPC clients, activity stream consumer feeding tea.Msg updates.

services/cli (Go)

  • cmd/ration/main.go — cobra-based: ration seed (creates 3 demo tenants with realistic reserve floors), ration simulate-deposit --tenant --amount --late (drives the late-deposit scenario judges will want to see), ration status --tenant.

Cross-cutting

  • pkg/pb/ — generated Go stubs (checked in after make proto, so judges don't need protoc to build).
  • pkg/money/money.go — Go mirror of the Money type + formatting helpers, imported by gateway/agent/tui/cli.
  • Structured logging (log/slog) everywhere in Go; tracing crate in Rust. Every state-changing call logs tenant_id, action, before/after balance.