Architecture

This page summarizes the rails-core layout from rails-core/docs/architecture.md. It describes the open-source multi-service stack behind the HTTP API—not your own product frontends.

System diagram

SDK Official backend clients

REST / GraphQL

NGINX Gateway

Rails API

Rust Users

Rust Accounts

Rails Ledger Engine

gRPC Mesh

Database Neon, Supabase, or your own Postgres

Mental model

Traffic hits a single nginx gateway on port 8080. The gateway forwards path prefixes to three domain services; each service has its own Postgres (no shared database, no cross-import of internal code). Services integrate over HTTP through the gateway and over gRPC/proto contracts for machine-to-machine shapes.

Request path

A typical financial command flows client → gateway → accounts → ledger → response: accounts validates and persists its bounded context, then invokes the ledger when a fact must be final; the ledger applies double-entry rules. Exact HTTP routes live in each service’s router; prefixes are stable at the gateway.

Gateway prefixes

Prefix	Service	Role (high level)
/users/	users-service (Rust)	Identity, auth edges, tenant context
/accounts/	accounts-service (Rust)	Accounts, balances, orchestration toward ledger
/ledger/	ledger-service (Rails)	Immutable ledger, postings, financial finality
/docs/	Static files	Developer docs served through the gateway

Contracts

Versioned proto files under proto/ define RPC surfaces (for example users.proto, accounts.proto, ledger.proto). Add or change RPCs in proto before implementing cross-service calls; version bumps follow your team’s policy (new package version or new file).

Why it is split

• Blast radius — A defect in a peripheral layer must not corrupt ledger data.
• Data isolation — Each service owns its database URL; no cross-DB joins.
• Velocity — Shared contracts stabilize integration while internals stay private.

For commands, env variables, and health checks, use rails-core/docs/quickstart.md alongside rails-core/README.md.