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

# Architecture

> How the marketplace, billing engine and orchestrator fit together.

GPU Outlet is split into three loosely-coupled subsystems. Understanding the
seam between them makes the dashboard's behavior obvious.

## The three subsystems

<CardGroup cols={3}>
  <Card title="Marketplace" icon="store">
    The listings sellers publish and buyers browse. Aggregates every live
    listing into one queryable catalog, with each listing's trust signals,
    price, and availability.
  </Card>

  <Card title="Orchestrator" icon="play">
    Reserves and launches the machine behind a listing on the buyer's behalf,
    injects their SSH key, and tears it down on stop.
  </Card>

  <Card title="Billing engine" icon="wallet">
    Prepaid wallet, Stripe integration, per-second metering, ledger, and seller
    earnings. The only component that handles money.
  </Card>
</CardGroup>

## Request flow

```mermaid theme={null}
sequenceDiagram
  participant B as Buyer
  participant D as Dashboard (SPA)
  participant S as API server
  participant M as Marketplace
  participant Seller as Seller machine

  B->>D: Pick a listing + template
  D->>S: Preview rental
  S->>M: Price + availability for the listing
  M-->>S: Quote
  S-->>D: Preview {price, eta}
  B->>D: Confirm
  D->>S: Create rental
  S->>S: Debit wallet (atomic)
  S->>Seller: Launch machine + inject SSH key
  Seller-->>S: Host address + port
  S-->>D: Rental {id, host, port}
  Note over S,Seller: Machine runs<br/>S meters every second
  S->>S: Decrement buyer wallet, accrue seller earnings
  B->>D: Click "Stop"
  D->>S: Stop rental
  S->>Seller: Terminate
  S->>S: Settle final usage
```

Every transaction passes through the API server so the wallet stays consistent,
the buyer's identity is attested, and the seller is credited for exactly the
seconds their machine ran.

## Consistency

Money is the part that can't tolerate races. The wallet uses row-level locking
on every debit, so concurrent metering ticks from multiple running instances
can't push a balance past zero, and the ledger is append-only — every deposit,
hold, charge, refund, and seller earning is a new immutable entry rather than an
edit to an old one.