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

259 lines
13 KiB
Markdown

# 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.