broker/ARCHITECTURE.md

# Broker Architecture

Smart order router and multi-venue execution engine. Single Go binary (`brokerd`), 16 venue adapters, institutional-grade order routing with net-price optimization.

## Design Principles

1. Single process. No microservices. One binary handles routing, risk, execution, settlement, compliance, market data, and streaming.
2. Venue adapters are the only abstraction. Everything else is concrete.
3. All order flow passes through risk engine before reaching any venue.
4. Market data is aggregated in-process. No external message bus required (NATS available but optional).
5. Secrets from KMS. Never in manifests, never in env files committed to git.

## System Topology

```
                                  Clients
                                    |
                              TLS (Cloudflare)
                                    |
                           hanzoai/gateway
                           (api.lux.network)
                                    |
                          +---------+---------+
                          |     brokerd       |
                          |     :8090         |
                          +---+---+---+---+---+
                              |   |   |   |
               +--------------+   |   |   +--------------+
               |                  |   |                   |
          +----+----+      +------+------+         +------+------+
          |  Router |      | Risk Engine |         |  Settlement |
          |  (SOR)  |      | (pre-trade) |         |   (pool)    |
          +----+----+      +-------------+         +------+------+
               |                                          |
     +---------+---------+                          +-----+-----+
     |    Market Data    |                          |   Funding  |
     |  Feed (BBO agg)  |                          | (deposit/  |
     +---+---+---+---+--+                          |  withdraw) |
         |   |   |   |                             +------------+
     +---+---+---+---+---+---+---+---+
     | Provider Adapters (16 venues) |
     +---+---+---+---+---+---+---+---+
         |   |   |   |   |   |   |
        CB  KRK BIN GEM SFOX FLX LMAX  ...
```

## Component Responsibilities

### Router (`pkg/router/`)

The smart order router. Stateless decision engine.

**Input:** Symbol, side (buy/sell), quantity.

**Decision algorithm:**

1. Fan out `GetAsset` + `GetSnapshot` to all registered providers in parallel (goroutines, channel collection).
2. Filter: drop providers where asset is not tradable or snapshot fails.
3. Score each venue: `net_price = raw_price * (1 + taker_fee_bps / 10000)` for buys; `raw_price * (1 - taker_fee_bps / 10000)` for sells (negated so higher net = better).
4. Sort ascending by score. Index 0 is best.
5. Return ranked list.

**Split execution (VWAP):**

1. Get all routes (same as above).
2. Filter to routes with live quotes.
3. Weight inversely proportional to score: better score = more volume.
4. Allocate quantity proportionally. Last leg absorbs rounding remainder.
5. Calculate estimated VWAP, fees, net price, and savings vs. single-venue worst case.
6. Execute all legs in parallel via `CreateOrder` with `type=market`, `time_in_force=ioc`.
7. Aggregate fills: compute actual VWAP from weighted average of fill prices.

**Fee schedule:** Hard-coded defaults per provider (see `defaultFees()`). Override at runtime via `SetFees()`.

```
Provider     Maker/Taker (bps)    Notes
-----------  ------------------   -----
alpaca       0/0                  Commission-free equities
binance      10/10                Standard tier
kraken       16/26                Standard tier
sfox         15/25                Prime dealer
coinbase     40/60                Advanced Trade
gemini       20/40                ActiveTrader
falcon       5/10                 Institutional RFQ
lmax         2/3                  Institutional CLOB
ibkr         0.5/0.5             Per-share approximation
```

### Market Data Feed (`pkg/marketdata/`)

In-process consolidated order book and ticker aggregation.

**Data model:**
- `Ticker`: per-symbol, aggregates quotes from all providers. Tracks best bid, best ask, spread (absolute + bps), provider attribution for each side.
- `ConsolidatedBook`: per-symbol, sorted bid/ask levels with provider tags.
- `Quote`: per-provider raw quote (bid/ask price+size, last price).

**Update flow:**
1. Provider snapshot polled or WebSocket update arrives.
2. `UpdateQuote(symbol, provider, bid, ask, bidSize, askSize, last)` called.
3. Feed recalculates BBO across all providers: highest bid wins, lowest ask wins.
4. Computes cross-venue spread: `best_ask - best_bid` (can be negative = arbitrage).
5. Notifies all subscribers via non-blocking channel send.

**Arbitrage detection:** When `best_bid_provider != best_ask_provider` and `best_bid > best_ask`, there is a cross-venue arbitrage. The router exposes this through the `/v1/bbo/{symbol}` endpoint. Execution is the client's responsibility.

**Polling vs. streaming:**
- SSE streaming via `pkg/ws/`: clients subscribe to symbols, receive consolidated ticker updates.
- Snapshot polling via `Feed.PollSnapshots()`: background goroutine polls all providers at configurable interval (default: provider-dependent, typically 1-5s for crypto).
- WebSocket feeds from venues (Binance, Kraken, Coinbase) update the feed directly when available.

### Risk Engine (`pkg/risk/`)

Pre-trade validation. Synchronous. Blocks order submission if any check fails.

**Checks (in order):**
1. Provider allowlist (global).
2. Symbol blocklist (global + per-account).
3. Symbol allowlist (per-account, if configured).
4. Order value vs. max single order limit.
5. Daily volume accumulator vs. daily limit.
6. Open order count vs. concurrent order limit.
7. Rate limit: orders per minute (sliding window from timestamps).

**Limits hierarchy:** Per-account overrides global. Global defaults: $1M max order, $10M daily, 100 open orders, 60 orders/min.

**Usage tracking:** In-memory. Daily counters reset after 24h. Rate limit uses a sliding window of order timestamps.

### Settlement Engine (`pkg/settlement/`)

Prefunding pool for instant crypto buys while ACH settles.

**Flow:**
```
User "Buy 1 BTC" -> Validate KYC tier limit
                  -> Check outstanding exposure
                  -> Reserve pool capital (amount = qty * price)
                  -> Execute trade on best venue (caller)
                  -> Initiate ACH (caller)
                  -> Track lifecycle:
                       ACH clears  -> Release pool credit
                       ACH fails   -> Mark for liquidation
                       Price drops  -> Margin call / auto-liquidate
```

**KYC tiers:**
```
basic          $250       Email-verified
standard       $5,000     ID-verified
enhanced       $25,000    Full KYC + accredited
institutional  $250,000   Institutional accounts
```

**Margin policy:** Configurable thresholds. Default: 20% warning, 30% margin call, 50% auto-liquidation. `CheckMarginHealth()` scans all pending reservations against current prices.

**Pool:** In-memory reservation store. Each reservation tracks: account, asset, amount, entry price, status, timestamps, events. Statuses: `pending_settlement`, `settled`, `failed`, `margin_called`, `liquidated`.

### Provider Interface (`pkg/provider/`)

```go
type Provider interface {
    Name() string
    CreateAccount(ctx, req)    // Onboarding
    GetAccount(ctx, id)        // Account detail
    ListAccounts(ctx)          // All accounts
    GetPortfolio(ctx, id)      // Holdings snapshot
    CreateOrder(ctx, id, req)  // Place order
    ListOrders(ctx, id)        // Order history
    GetOrder(ctx, id, oid)     // Order detail
    CancelOrder(ctx, id, oid)  // Cancel
    CreateTransfer(ctx, id, r) // Fund movement
    ListTransfers(ctx, id)     // Transfer history
    CreateBankRelationship()   // Link bank
    ListBankRelationships()    // List banks
    ListAssets(ctx, class)     // Tradable instruments
    GetAsset(ctx, symbol)      // Asset detail
    GetSnapshot(ctx, symbol)   // Real-time price
    GetSnapshots(ctx, syms)    // Batch snapshots
    GetBars(ctx, ...)          // Historical OHLCV
    GetLatestTrades(ctx, syms) // Latest trades
    GetLatestQuotes(ctx, syms) // Latest quotes
    GetClock(ctx)              // Market hours
    GetCalendar(ctx, s, e)     // Trading calendar
}
```

**Optional capability interfaces** (type-asserted at runtime):
- `TradingExtended` -- Replace, cancel-all, positions.
- `AccountManager` -- Update, close, activities.
- `DocumentManager` -- Upload, list, download.
- `JournalManager` -- Inter-account transfers (JNLC/JNLS).
- `TransferExtended` -- Cancel transfer, ACH deletion, wire banks.
- `CryptoDataProvider` -- Crypto-specific bars/quotes/trades/snapshots.
- `EventStreamer` -- SSE streams for trade/account/transfer/journal events.
- `PortfolioAnalyzer` -- Portfolio equity history.
- `WatchlistManager` -- CRUD watchlists.

**Provider registration:** `pkg/provider/envconfig/` reads 16 sets of env vars and registers configured providers. Breaks import cycle: envconfig imports provider sub-packages, provider sub-packages import the provider interface package.

### Venues

| Provider | Pkg | Asset Classes | Execution | Market Data |
|----------|-----|--------------|-----------|-------------|
| Alpaca | `provider/alpaca/` | Equities, Crypto | Full (100% API) | Stocks + Crypto |
| Interactive Brokers | `provider/ibkr/` | Equities, Options, Futures, FX, Crypto | Full | Full |
| Tradier | `provider/tradier/` | Equities, Options | Full | Full |
| Coinbase | `provider/coinbase/` | Crypto | Advanced Trade | Full |
| Binance | `provider/binance/` | Crypto | Spot/Margin | Full |
| Kraken | `provider/kraken/` | Crypto | Full | Full |
| Gemini | `provider/gemini/` | Crypto | Full | Full |
| SFOX | `provider/sfox/` | Crypto | Market/Limit + Algo | Best-price + OHLCV |
| FalconX | `provider/falcon/` | Crypto | RFQ | Quotes |
| Fireblocks | `provider/fireblocks/` | Crypto | Transfer/Custody | Balances |
| BitGo | `provider/bitgo/` | Crypto | Custody + Prime | Balances |
| Circle | `provider/circle/` | Stablecoins | Mint/Burn/Transfer | Balances |
| CurrencyCloud | `provider/currencycloud/` | FX (35+ pairs) | Spot/Forward | Rates |
| LMAX | `provider/lmax/` | FX, Crypto, Metals | CLOB | Full |
| Polygon.io | `provider/polygon/` | Equities, FX, Crypto, Options | Data only | Full |
| Finix | `provider/finix/` | Payments | ACH/Wire/Card | N/A |

### Compliance (`pkg/compliance/`)

KYC/KYB onboarding, fund management, eSign, RBAC, reporting. Mounted at `/compliance`. PostgreSQL or in-memory store. AML/fraud screening runs against the OFAC SDN list and the ScamSniffer scam-address database, with the native `github.com/luxfi/aml` engine (`amld`) as the deeper risk-scoring backend, plus a webhook dispatcher (`compliance/webhooks/`).

### Audit (`pkg/audit/`)

Append-only log of every order, fill, cancellation, transfer. Queryable by action, provider, account, symbol, time range. Exportable as JSON.

### Auth (`pkg/auth/` + `pkg/admin/`)

- **API auth:** API key or Bearer token validation. Keys scoped to org via IAM OIDC `owner` claim.
- **Admin auth:** JWT (HMAC-SHA256). Password hashed (SHA-256 + salt). Admin users from env vars.

## Data Flow: Smart Order Execution

```
Client POST /v1/smart-order
  |
  v
API Server (auth middleware validates JWT/API key)
  |
  v
Risk Engine: PreTradeCheck(provider, account, symbol, side, qty, price)
  |-- REJECT if any check fails (returns errors)
  |-- WARN if approaching limits (returns warnings)
  |
  v
Router: FindBestProvider(ctx, symbol, side)
  |-- Fan out GetAsset + GetSnapshot to all providers (parallel)
  |-- Score: net_price = raw_price * (1 +/- fee_bps)
  |-- Return best provider
  |
  v
Provider: CreateOrder(ctx, accountID, request)
  |-- HTTP to venue API
  |-- Return unified Order struct
  |
  v
Audit: Record(action=order_created, provider, account, symbol, ...)
  |
  v
Risk Engine: RecordOrder(provider, account, orderValue)
  |
  v
Client receives Order response
```

## Data Flow: Split Order (VWAP)

```
Client POST /v1/smart-order/split
  |
  v
Router: BuildSplitPlan(ctx, symbol, side, qty)
  |-- GetAllRoutes (parallel venue polling)
  |-- Score-weighted allocation
  |-- Return SplitPlan with legs
  |
  v
Router: ExecuteSplitPlan(ctx, plan, accounts)
  |-- For each leg (parallel goroutines):
  |     Provider.CreateOrder(ctx, accountID, {type:market, tif:ioc})
  |-- Collect results via channel
  |-- Compute actual VWAP = sum(price_i * filled_i) / sum(filled_i)
  |
  v
Return ExecutionResult {vwap, legs[], status, latency}
```

## Data Flow: Market Data Aggregation

```
Background poller (configurable interval)
  |
  v
For each registered provider (parallel):
  Provider.GetSnapshot(ctx, symbol)
  |
  v
Feed.UpdateQuote(symbol, provider, bid, ask, sizes, last)
  |-- Update per-provider quote in ticker
  |-- Recalculate BBO: max(bids), min(asks) across providers
  |-- Compute spread + spread_bps
  |-- Notify subscribers (non-blocking channel send)
  |
  v
SSE Server: HandleSSE streams to connected clients
  |-- event: ticker
  |-- data: {symbol, best_bid, best_ask, spread, sources{}}
```

## API Surface

```
/healthz                              Health check (no auth)

/v1/route/{symbol}                    Best venues for symbol
/v1/route/{symbol}/split              VWAP split plan
/v1/smart-order                       Execute via best venue
/v1/smart-order/split                 Execute split across venues
/v1/bbo/{symbol}                      Best bid/offer (cross-venue)
/v1/stream                            SSE consolidated tickers
/v1/assets                            Aggregated tradable assets

/v1/accounts                          CRUD accounts
/v1/accounts/{p}/{id}/orders          CRUD orders
/v1/accounts/{p}/{id}/positions       Positions
/v1/accounts/{p}/{id}/transfers       Transfers
/v1/accounts/{p}/{id}/portfolio       Portfolio snapshot

/v1/market/{provider}/snapshot/{sym}  Per-venue snapshot
/v1/market/{provider}/bars/{sym}      Historical OHLCV
/v1/risk/check                        Pre-trade risk check
/v1/audit                             Query audit log

/v1/providers                         Registered providers
/v1/providers/capabilities            Provider feature matrix

/compliance/*                         KYC/KYB, onboarding, RBAC
```

## Deployment

### Single Binary

```
brokerd
  |- HTTP server (:8090)
  |- Provider registry (16 adapters, env-configured)
  |- Router (SOR)
  |- Risk engine
  |- Market data feed + SSE
  |- Settlement service + pool
  |- Compliance router (PostgreSQL or in-memory)
  |- Audit log
  |- Admin JWT auth
```

### K8s (lux-k8s cluster)

```yaml
Namespace: broker
Deployment: broker (1 replica, scales horizontally)
  Image: ghcr.io/luxfi/broker:{tag}
  Port: 8090
  Resources: 100m-500m CPU, 64Mi-256Mi RAM
  Probes: /healthz (readiness 5s, liveness 30s)
  Secrets: broker-secrets (KMSSecret CRD -> kms.hanzo.ai)
Service: broker:8090
Ingress: via hanzoai/gateway at api.lux.network
```

**Secrets flow:**
```
kms.hanzo.ai (Hanzo KMS)
  -> KMSSecret CRD in broker namespace
  -> K8s Secret: broker-secrets
  -> Pod env: DATABASE_URL, ALPACA_API_KEY, etc.
```

### compose.yml (local dev)

```
services:
  sql: postgres:17-alpine on :5434
```

Broker runs natively (`make run`) against the local Postgres and configured provider sandboxes.

### CI/CD

Image built by PaaS (platform.hanzo.ai) via Tekton pipeline. Cloud Build config exists for GCP fallback (`cloudbuild.yaml`). Images pushed to `ghcr.io/luxfi/broker:{tag}`.

## Technology Choices

| Choice | Rationale |
|--------|-----------|
| Go | Low-latency order routing requires predictable GC, goroutines for parallel venue polling, stdlib HTTP. |
| Single binary | No inter-service latency for routing decisions. One process = one failure domain. |
| chi router | stdlib-compatible, middleware chains, zero allocation routing. |
| zerolog | Structured JSON logging, zero allocation. |
| pgx/v5 | PostgreSQL driver for compliance store. Direct, no ORM. |
| NATS (go.mod) | Available for inter-process pub/sub if broker scales to multiple instances. Not required for single-instance. |
| SSE over WebSocket | Works through all proxies/load balancers. Simpler. Sufficient for ticker updates. |
| In-memory risk/settlement | Latency-critical paths. PostgreSQL for durable compliance data. |

## Scaling Path

The broker is designed to scale horizontally when needed:

1. **Current:** Single instance handles all routing, risk, execution. Sufficient for <10k orders/day.
2. **Next:** NATS for cross-instance market data fan-out. Sticky sessions for settlement state. PostgreSQL for risk state.
3. **Future:** Dedicated market data service (separate binary from same codebase). Sharded by asset class.

The single-binary architecture means "scaling" is primarily about running more replicas behind the gateway, not decomposing into microservices.

## Related Systems

| System | Relationship |
|--------|-------------|
| `luxfi/compliance` | Extracted compliance module (KYC/AML) |
| `luxfi/bank` | Customer-facing apps consuming broker API |
| `hanzoai/commerce` | Payment processors (Plaid, Braintree, Stripe) used by funding service |
| `hanzoai/iam` | Identity provider. Broker validates OIDC tokens, scopes to org. |
| `kms.hanzo.ai` | All provider credentials. KMSSecret CRDs sync to K8s. |