# rossku/kob architecture

> Architecture diagram of the GitHub repository rossku/kob, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rossku/kob
- Repository: https://github.com/rossku/kob

## Overview

KOB is a permissionless Kaspa token order book: makers create covenant-backed orders, and anyone can match them. The main user workflow runs through the web app: inspect markets and order books, submit wallet-approved transactions, then follow orders and fills. A separate kobd indexer serves chain-derived data; its Executor role runs the matcher. The CLI offers parallel trading and recovery workflows, while shared protocol and x402 components support covenant construction and payments. Edges below are limited to README statements and source-index references; many implementation details were not sampled.

Main entry points: [`web/src/app/App.tsx`](https://github.com/rossku/kob/blob/master/web/src/app/App.tsx) (Web app), [`crates/kobd/src/indexer/ingest.rs`](https://github.com/rossku/kob/blob/master/crates/kobd/src/indexer/ingest.rs) (Chain indexer), [`web/src/app/services.ts`](https://github.com/rossku/kob/blob/master/web/src/app/services.ts) (Data services), [`crates/kobd/src/app.rs`](https://github.com/rossku/kob/blob/master/crates/kobd/src/app.rs) (kobd runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web trading app"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_webboot["App bootstrap<br/>[main.tsx]"]
  node_webservices["Data services<br/>[services.ts]"]
  node_market["Markets and books<br/>[MarketView.tsx]"]
  node_orders["Orders and balances<br/>[OrdersView.tsx]"]
  node_signer["Isolated signer<br/>[main.ts]"]
end

subgraph group_daemon["Node services"]
  node_daemon["kobd runtime<br/>[app.rs]"]
  node_config["Service configuration<br/>[config.rs]"]
  node_indexer["Chain indexer<br/>[ingest.rs]"]
  node_indexdb[("Indexer storage<br/>[db.rs]")]
  node_matcher["Order matcher<br/>[engine.rs]"]
  node_api["Read API<br/>[rest.rs]"]
end

subgraph group_protocol["Trading protocol"]
  node_protocol["Covenant protocol<br/>[router.rs]"]
  node_wasm["Wasm bindings<br/>[lib.rs]"]
end

subgraph group_clients["CLI and Android"]
  node_cli["Trading CLI<br/>[main.rs]"]
  node_cli_trading["CLI trade flows<br/>[flow.rs]"]
  node_android["Android executor<br/>[ExecutorService.kt]"]
end

subgraph group_x402["x402 payments"]
  node_x402_client["Payment client SDK<br/>[client.ts]"]
  node_x402_server["Paywall server SDK<br/>[server.ts]"]
  node_facilitator["Payment facilitator<br/>[facilitator.rs]"]
  node_x402_core["Payment protocol<br/>[lib.rs]"]
end

node_trader(("Trader"))

node_trader -->|"uses"| node_webapp
node_webboot -->|"starts"| node_webapp
node_webapp -->|"routes"| node_market
node_webapp -->|"routes"| node_orders
node_webapp -->|"uses data"| node_webservices
node_webapp -.->|"requests signing"| node_signer
node_webservices -->|"queries"| node_indexer
node_webservices -->|"loads"| node_wasm
node_webservices -.->|"uses"| node_api
node_daemon -->|"loads"| node_config
node_daemon -->|"runs"| node_matcher
node_indexer -->|"commits"| node_indexdb
node_indexer -->|"tracks watches"| node_matcher
node_daemon -.->|"starts"| node_indexer
node_api -.->|"reads"| node_indexdb
node_matcher -.->|"builds transactions"| node_protocol
node_cli -->|"dispatches"| node_cli_trading
node_trader -->|"runs commands"| node_cli
node_cli -.->|"plans transactions"| node_protocol
node_android -.->|"runs executor"| node_daemon
node_x402_client -.->|"pays resource"| node_x402_server
node_x402_server -->|"submits settlement"| node_facilitator
node_facilitator -.->|"tracks payments"| node_indexer
node_x402_client -.->|"uses protocol"| node_x402_core

click node_webapp "https://github.com/rossku/kob/blob/master/web/src/app/App.tsx"
click node_webboot "https://github.com/rossku/kob/blob/master/web/src/main.tsx"
click node_webservices "https://github.com/rossku/kob/blob/master/web/src/app/services.ts"
click node_market "https://github.com/rossku/kob/blob/master/web/src/ui/market/MarketView.tsx"
click node_orders "https://github.com/rossku/kob/blob/master/web/src/ui/orders/OrdersView.tsx"
click node_signer "https://github.com/rossku/kob/blob/master/web/src/signer/main.ts"
click node_daemon "https://github.com/rossku/kob/blob/master/crates/kobd/src/app.rs"
click node_config "https://github.com/rossku/kob/blob/master/crates/kobd/src/config.rs"
click node_indexer "https://github.com/rossku/kob/blob/master/crates/kobd/src/indexer/ingest.rs"
click node_indexdb "https://github.com/rossku/kob/blob/master/crates/kobd/src/indexer/db.rs"
click node_matcher "https://github.com/rossku/kob/blob/master/crates/kobd/src/matcher/engine.rs"
click node_api "https://github.com/rossku/kob/blob/master/crates/kobd/src/api/rest.rs"
click node_protocol "https://github.com/rossku/kob/blob/master/crates/kob-protocol/src/router.rs"
click node_wasm "https://github.com/rossku/kob/blob/master/crates/kob-wasm/src/lib.rs"
click node_cli "https://github.com/rossku/kob/blob/master/crates/kob-cli/src/main.rs"
click node_cli_trading "https://github.com/rossku/kob/blob/master/crates/kob-cli/src/trade/flow.rs"
click node_android "https://github.com/rossku/kob/blob/master/android/app/src/main/kotlin/org/kob/executor/ExecutorService.kt"
click node_x402_client "https://github.com/rossku/kob/blob/master/packages/kob-x402/src/client.ts"
click node_x402_server "https://github.com/rossku/kob/blob/master/packages/kob-x402/src/server.ts"
click node_facilitator "https://github.com/rossku/kob/blob/master/crates/kobd/src/x402/facilitator.rs"
click node_x402_core "https://github.com/rossku/kob/blob/master/crates/kob-x402/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_webboot,node_webservices,node_market,node_orders,node_signer toneBlue
class node_daemon,node_config,node_indexer,node_indexdb,node_matcher,node_api toneAmber
class node_protocol,node_wasm toneMint
class node_cli,node_cli_trading,node_android toneRose
class node_x402_client,node_x402_server,node_facilitator,node_x402_core,node_trader toneIndigo
```

## Components

### Web trading app

- [Web app](https://github.com/rossku/kob/blob/master/web/src/app/App.tsx): `web/src/app/App.tsx`
- [App bootstrap](https://github.com/rossku/kob/blob/master/web/src/main.tsx): `web/src/main.tsx`
- [Data services](https://github.com/rossku/kob/blob/master/web/src/app/services.ts): `web/src/app/services.ts`
- [Markets and books](https://github.com/rossku/kob/blob/master/web/src/ui/market/MarketView.tsx): `web/src/ui/market/MarketView.tsx`
- [Orders and balances](https://github.com/rossku/kob/blob/master/web/src/ui/orders/OrdersView.tsx): `web/src/ui/orders/OrdersView.tsx`
- [Isolated signer](https://github.com/rossku/kob/blob/master/web/src/signer/main.ts): `web/src/signer/main.ts`

### Node services

- [kobd runtime](https://github.com/rossku/kob/blob/master/crates/kobd/src/app.rs): `crates/kobd/src/app.rs`
- [Service configuration](https://github.com/rossku/kob/blob/master/crates/kobd/src/config.rs): `crates/kobd/src/config.rs`
- [Chain indexer](https://github.com/rossku/kob/blob/master/crates/kobd/src/indexer/ingest.rs): `crates/kobd/src/indexer/ingest.rs`
- [Indexer storage](https://github.com/rossku/kob/blob/master/crates/kobd/src/indexer/db.rs): `crates/kobd/src/indexer/db.rs`
- [Order matcher](https://github.com/rossku/kob/blob/master/crates/kobd/src/matcher/engine.rs): `crates/kobd/src/matcher/engine.rs`
- [Read API](https://github.com/rossku/kob/blob/master/crates/kobd/src/api/rest.rs): `crates/kobd/src/api/rest.rs`

### Trading protocol

- [Covenant protocol](https://github.com/rossku/kob/blob/master/crates/kob-protocol/src/router.rs): `crates/kob-protocol/src/router.rs`
- [Wasm bindings](https://github.com/rossku/kob/blob/master/crates/kob-wasm/src/lib.rs): `crates/kob-wasm/src/lib.rs`

### CLI and Android

- [Trading CLI](https://github.com/rossku/kob/blob/master/crates/kob-cli/src/main.rs): `crates/kob-cli/src/main.rs`
- [CLI trade flows](https://github.com/rossku/kob/blob/master/crates/kob-cli/src/trade/flow.rs): `crates/kob-cli/src/trade/flow.rs`
- [Android executor](https://github.com/rossku/kob/blob/master/android/app/src/main/kotlin/org/kob/executor/ExecutorService.kt): `android/app/src/main/kotlin/org/kob/executor/ExecutorService.kt`

### x402 payments

- [Payment client SDK](https://github.com/rossku/kob/blob/master/packages/kob-x402/src/client.ts): `packages/kob-x402/src/client.ts`
- [Paywall server SDK](https://github.com/rossku/kob/blob/master/packages/kob-x402/src/server.ts): `packages/kob-x402/src/server.ts`
- [Payment facilitator](https://github.com/rossku/kob/blob/master/crates/kobd/src/x402/facilitator.rs): `crates/kobd/src/x402/facilitator.rs`
- [Payment protocol](https://github.com/rossku/kob/blob/master/crates/kob-x402/src/lib.rs): `crates/kob-x402/src/lib.rs`

### Other components

- **Trader**

## Connections

- Trader → Web app: uses
- App bootstrap → Web app: starts (evidence: `web/src/main.tsx`)
- Web app → Markets and books: routes (evidence: `web/src/app/App.tsx`)
- Web app → Orders and balances: routes (evidence: `web/src/app/App.tsx`)
- Web app → Data services: uses data (evidence: `web/src/app/services.ts`)
- Web app → Isolated signer: requests signing
- Data services → Chain indexer: queries (evidence: `web/src/app/services.ts`)
- Data services → Wasm bindings: loads (evidence: `web/src/app/services.ts`)
- Data services → Read API: uses
- kobd runtime → Service configuration: loads (evidence: `crates/kobd/src/app.rs`)
- kobd runtime → Order matcher: runs (evidence: `crates/kobd/src/app.rs`)
- Chain indexer → Indexer storage: commits (evidence: `crates/kobd/src/indexer/ingest.rs`)
- Chain indexer → Order matcher: tracks watches (evidence: `crates/kobd/src/indexer/ingest.rs`)
- kobd runtime → Chain indexer: starts
- Read API → Indexer storage: reads
- Order matcher → Covenant protocol: builds transactions
- Trading CLI → CLI trade flows: dispatches (evidence: `crates/kob-cli/src/main.rs`)
- Trader → Trading CLI: runs commands
- Trading CLI → Covenant protocol: plans transactions
- Android executor → kobd runtime: runs executor
- Payment client SDK → Paywall server SDK: pays resource (evidence: `packages/kob-x402/src/server.ts`)
- Paywall server SDK → Payment facilitator: submits settlement (evidence: `packages/kob-x402/src/server.ts`)
- Payment facilitator → Chain indexer: tracks payments
- Payment client SDK → Payment protocol: uses protocol