global: snapshot

docs/ARCHITECTURE.md

@@ -0,0 +1,99 @@
+# Architecture
+
+## Overview
+
+```
+blk*.dat ──▶ Reader ──┐
+                      ├──▶ Indexer ──▶ Computer ──┐
+         RPC Client ──┤                           ├──▶ Query ──▶ Server
+                      └──▶ Mempool ───────────────┘
+```
+
+## Components
+
+### Reader (`brk_reader`)
+
+Parses Bitcoin Core's `blk*.dat` files directly, bypassing RPC for historical data. Supports parallel parsing and handles XOR-encoded blocks (Bitcoin Core 28+).
+
+### RPC Client (`brk_rpc`)
+
+Connects to Bitcoin Core for real-time data: new blocks, mempool transactions, and fee estimates. Thread-safe with automatic retries.
+
+### Indexer (`brk_indexer`)
+
+Builds lookup tables from parsed blocks:
+- Transaction index (txid → block position)
+- Address index (address → transactions, UTXOs)
+- UTXO set tracking
+- Output type classification (P2PKH, P2WPKH, P2TR, etc.)
+
+### Computer (`brk_computer`)
+
+Derives analytics from indexed data:
+- Market metrics: realized cap, MVRV, SOPR, NVT
+- Supply metrics: circulating, liquid, illiquid
+- UTXO cohorts: by age, size, type
+- Address cohorts: by balance, activity
+- Pricing models: thermocap, realized price bands
+
+Metrics are computed across multiple time resolutions (daily, weekly, monthly, by block height).
+
+### Mempool (`brk_mempool`)
+
+Monitors unconfirmed transactions:
+- Fee rate distribution and estimation
+- Projected block templates
+- Address mempool activity
+
+### Query (`brk_query`)
+
+Unified interface to all data sources:
+- Block and transaction lookups
+- Address balances and history
+- Computed metrics with range queries
+- Mempool state
+
+### Server (`brk_server`)
+
+REST API exposing Query functionality:
+- OpenAPI documentation (Scalar UI)
+- JSON and CSV output formats
+- ETag caching
+- mempool.space compatible endpoints
+
+## Data Flow
+
+**Initial sync:**
+1. Reader parses all `blk*.dat` files in parallel
+2. Indexer processes blocks sequentially, building indexes
+3. Computer derives metrics from indexed data
+4. Server starts accepting requests
+
+**Ongoing operation:**
+1. RPC client polls for new blocks
+2. Reader fetches block data
+3. Indexer updates indexes
+4. Computer recalculates affected metrics
+5. Mempool monitors transaction pool
+
+## Storage
+
+Data is stored in `~/.brk/` (configurable):
+
+```
+~/.brk/
+├── indexer/     # Transaction and address indexes (fjall)
+├── computer/    # Computed metrics (vecdb)
+└── config.toml  # Configuration
+```
+
+Disk usage scales with blockchain size. Full index with metrics: ~400 GB.
+
+## Dependencies
+
+Built on:
+- [`rust-bitcoin`](https://github.com/rust-bitcoin/rust-bitcoin) - Bitcoin primitives
+- [`fjall`](https://github.com/fjall-rs/fjall) - LSM-tree storage
+- [`vecdb`](https://github.com/anydb-rs/anydb) - Vector storage
+- [`axum`](https://github.com/tokio-rs/axum) - HTTP server
+- [`aide`](https://github.com/tamasfe/aide) - OpenAPI generation