Architecture — Overview

AXON is a TypeScript microservices platform with three planes:

1. Frontends — a Next.js web/desktop app (plus an admin console and a reusable mobile screen layer).
2. Backend — ~12 NestJS services behind a single API gateway, sharing one PostgreSQL database.
3. On‑chain layer — a custom Solidity escrow contract and a collection wallet on Base (Coinbase's L2), accessed through the integration layer.

Everything external — wallets, identity, AI, fiat ramps, payouts — is reached through pluggable integration partners.

Solution architecture

System context

Integration partners

Everything external is reached through the integration layer (packages/integration-layer), so providers are pluggable and each carries its own status. The map below shows every partner, what it does, the AXON service that consumes it, and whether it's live, in sandbox, or planned.

• Identity & wallets — Privy (embedded wallets + SIWE auth) and Sumsub (KYC/KYB) are live; Sumsub runs in sandbox on the pilot.
• AI — OpenAI (gpt-4o) powers the assistant and contract drafting, with Anthropic as a planned alternate provider.
• Fiat on/off‑ramps — MoonPay, Onramper, Transak and Crossmint are wired and live in sandbox (each self‑activates once its keys are present); Wise provides cross‑border payout (quotes live). Banxa is coded against the common RampProvider interface but not yet keyed, and MoneyGram via Stellar SEP‑24 is announced (the stellar.toml domain is live; the adapter is pending).
• Treasury, payout & custody — Lydiam backs instant‑funding payouts (simulation on the pilot); Circle CPN is the deferred production‑custody path.
• Blockchain · Base — the AXONEscrow.sol contract, USDC/MockUSDC settlement asset, and the instant‑funding collection wallet, all on Base Sepolia.
• Infrastructure & DevOps — Cloudflare (DNS/CDN/WAF), Caddy (TLS/reverse proxy), AWS Lightsail (host), and GitHub Actions (CI/CD).

A new ramp or provider is added by implementing the relevant interface in the integration layer — no service code changes (see Developer → Conventions).

Design principles

• Gateway‑only access. No backend service is exposed publicly. The API gateway is the only internet‑facing service; it authenticates every request and proxies to internal services over a private Docker network. Each service re‑verifies the JWT in defence‑in‑depth.
• One database, many services. All services share a single PostgreSQL schema via the generated Prisma client (@axon/db). Services do not hold cross‑service foreign keys — links across service boundaries are loose string IDs (e.g. FundingCoverage.settlementId), so each service can evolve independently.
• Dual‑mode identity. A user can act as a Personal profile or one or more Business profiles. Each profile has its own embedded wallet (different HD indexes) and its own KYC/KYB status. Every money operation is stamped with the acting profile (X-AXON-Profile-Id) so personal and business activity never commingle.
• Prepare → sign → confirm. On‑chain actions are signed client‑side by the user's wallet; the backend prepares the call, then verifies the resulting transaction against the chain before mutating database state. The chain — not the API — is the source of truth for custody.
• Canonical operation hashes. Off‑chain records and on‑chain events are linked by an operationHash (a UUID encoded as bytes32, byte‑identical to the contract's offChainId), so any record can be traced to its on‑chain proof and back.
• Audit‑ready by construction. Money movements are written to an append‑only, hash‑chained settlement ledger whose head is periodically anchored to Base. Tampering is detectable; history is provable.

Technology at a glance

Continue to System components for what each piece does, or jump to Key flows to see how a request travels through the system.