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>
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— buildslibwal.a(static lib) consumed by Rust via FFI, plustest_walbinary.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 (LedgerCoreservice fromledger.proto).src/money.rs—Moneytype, checked arithmetic, currency mismatches are a typed error, not a panic.src/wal_ffi.rs— the onlyunsafemodule; safe wrapper aroundlibwal.a.src/ledger.rs— core domain:apply_entry(idempotent onidempotency_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—LedgerCoretrait 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 (forSimulateDepositonly), card-issuance client, webhook-ingestion client (relayed into the local activity bus), gRPC server forgateway.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 aroundcardissuance.CardIssuanceClient.internal/webhookeventsclient/client.go— typed gRPC client wrapper that subscribes to webhook-ingestion'sStreamEventsand republishes every event onto gateway's owninternal/activitybus.internal/ledgerclient/client.go— typed gRPC client wrapper aroundledger.LedgerCoreClient, used only bySimulateDepositnow.internal/activity/stream.go— fan-out event bus (Go channels) feedingStreamActivitygRPC 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.protoservice impl: each method either translates to acardissuanceclientcall (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.gonext 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 forauth.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.protoservice impl, wires the above. Not yet dialed by gateway or any other service — seedocs/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 fortenant_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 aroundledger.LedgerCoreClient(each split service gets its own copy, not a shared import — seedocs/adr/0004).internal/grpcserver/server.go—tenant_registry.protoservice 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 perAIRWALLEX_MODE), gRPC server forcard_issuance.proto.internal/config/config.go— Airwallex + bridge-policy env loading (this service's share of the old gateway'sinternal/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 (seeAGENT-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'sbridge/service_test.gocases 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 aroundledger.LedgerCoreClient.internal/grpcserver/server.go—card_issuance.protoservice impl, a direct passthrough tocardsvc/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 owninternal/grpcserveris where thecardissuance.*<->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 forwebhook_ingestion.protoand 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 inAIRWALLEX_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, turnsglobal_account.transaction.createdinto aMarkDepositReceivedcall against ledger-core, publishes a normalized event either way.internal/eventbus/eventbus.go— fan-out event bus (Go channels) feedingwebhook_ingestion.proto'sStreamEventsRPC — the documented subscriber is gateway's owninternal/webhookeventsclient, merging these events into its activity feed.internal/ledgerclient/client.go— this service's own typed gRPC client wrapper aroundledger.LedgerCoreClient.internal/grpcserver/server.go—webhook_ingestion.protoservice impl (StreamEventsonly — 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 viaRATION_AGENT_MODEL, defaultclaude-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 vialedgerclient.RecordAgentDecisionfor audit (never silent).internal/llm/prompt.go— system prompt: the rationing policy in prose, explicit instruction to stay within the pre-computed hard envelope frompolicy/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-leveltea.Model, tab state (tenants / deposits / cards / activity feed).internal/view/tenants.go,deposits.go,cards.go,activity.go— one file per tab, each alipgloss-styled table/list.internal/client/grpc.go— gateway + ledger-core gRPC clients, activity stream consumer feedingtea.Msgupdates.
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 aftermake 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;tracingcrate in Rust. Every state-changing call logs tenant_id, action, before/after balance.