> ## Documentation Index
> Fetch the complete documentation index at: https://firmament.shaikazeem.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How the Firmament backend, web app, and runtime projection fit together.

# Architecture

Firmament has one Rust backend and two web surfaces.

* Rust crate: RFQ runtime, Axum HTTP API, SQLite persistence, Solana/Jupiter/Gateway adapters
* Vite app: taker swap demo at `/app` and runtime view at `/app/runtime`
* Next.js landing page: project positioning for demos and submissions

## Runtime path

```text theme={null}
RFQ request
  -> quote engine
  -> risk gate
  -> wallet-settlement terms
  -> taker lock / redeem records
  -> maker HTLC actions when live workers are enabled
  -> ledger and runtime events
  -> inventory repair checks
```

## Backend pieces

The RFQ API accepts a friendly shape (`input_asset`, `output_asset`, decimal
`amount` string) or the legacy mint/raw shape (`input_mint`, `output_mint`,
`input_amount_raw`) plus the taker wallet and an optional expiry. It returns
either accepted terms with display-friendly `pair`, `input`, `output`, and
`next_action` fields or a stable rejection reason with a user-facing
`message` and `suggested_action`.

The quote engine combines reference price, spread, inventory skew, fees, and minimum-profit policy.

The risk gate checks supported assets, supported pairs, notional caps, stale prices, allowlist policy, and available inventory.

Settlement uses the browser wallet for taker signatures. The backend tracks
trade state, observed signatures, and maker-side actions, and persists active
wallet settlements so the app can recover after a browser refresh or backend
restart. Legacy local-signing taker keypairs exist for tests; they are not
required for the web app.

SQLite stores ledger, P\&L, terminal trade summaries, and active settlement
recovery state. The public runtime endpoints expose derived ledger balances and
global recent trade summaries; trade rows include taker-wallet attribution when
the browser-wallet flow supplied it. Ledger endpoints do not expose wallet
addresses or secrets.

The browser keeps the settlement preimage locally until redeem time. The server
stores the hash commitment and signatures it needs to recover settlement state,
but it does not persist the preimage.

Jupiter and Circle Gateway are live adapters. They run only when protocol workers and required credentials are configured.

Jupiter config should point at Swap API V2 (`https://api.jup.ag/swap/v2`). The adapter uses `/order` plus `/execute` for managed swaps and keeps `/build` parsing covered for raw instruction tests.

Circle Gateway config uses the maker's approved Solana depositor address. Gateway deposits move Solana USDC into the unified balance; Gateway refill mints/transfers USDC back to the maker's Solana working wallet.

## Public boundary

Public docs cover the app-facing swap and runtime routes. Admin routes and the disabled legacy accept route are intentionally left out of the public reference.