Initial commit

doc/data-models.md

@@ -0,0 +1,108 @@
+# Data Models and Schema
+
+## Storage Backend
+
+- Database engine: SQLite.
+- Default file path: `./data/dashboard.db`.
+- Effective path is controlled by `DB_PATH`.
+
+Related references:
+
+- Configuration values: `doc/environment.md`
+- Persistence implementation: `app/db.py`
+
+## Tables
+
+### `node_settings`
+
+Single-row settings table used as the source of truth for RPC and SSH connectivity.
+
+Schema fields:
+
+- `id INTEGER PRIMARY KEY CHECK (id = 1)`
+- `rpc_url TEXT NOT NULL`
+- `rpc_username TEXT NOT NULL`
+- `rpc_password TEXT NOT NULL`
+- `rpc_wallet TEXT NOT NULL`
+- `config_path TEXT NOT NULL`
+- `ssh_host TEXT NOT NULL`
+- `ssh_port INTEGER NOT NULL`
+- `ssh_username TEXT NOT NULL`
+- `ssh_password TEXT NOT NULL`
+- `ssh_key_path TEXT NOT NULL`
+- `bitcoin_binary TEXT NOT NULL`
+- `updated_at TEXT NOT NULL` (UTC ISO 8601 string)
+
+Invariants:
+
+- Exactly one logical settings record exists with `id = 1`.
+- `save_settings` performs an upsert.
+- Missing settings row is represented by in-code defaults.
+
+### `metrics_history`
+
+Time-series table for chart data and historical dashboard views.
+
+Schema fields:
+
+- `ts INTEGER PRIMARY KEY` (Unix timestamp, seconds)
+- `blocks INTEGER NOT NULL`
+- `headers INTEGER NOT NULL`
+- `mempool_bytes INTEGER NOT NULL`
+- `peers INTEGER NOT NULL`
+
+Index:
+
+- `idx_metrics_history_ts` on `ts`
+
+Invariants:
+
+- A timestamp has at most one row.
+- Inserts on duplicate timestamp overwrite existing point.
+- Returned history is chronological for UI consumption.
+
+## Retention and Limits
+
+Retention behavior is enforced during each metric insert:
+
+- Time retention: rows older than 30 days are deleted.
+- Count retention: rows beyond the newest 20000 samples are deleted.
+- Query limit input is clamped to `[1, 20000]`.
+
+## Metric Sampling Sources
+
+A metric point is composed from RPC responses:
+
+- `blocks` and `headers` from `getblockchaininfo`
+- `mempool_bytes` from `getmempoolinfo.bytes`
+- `peers` from `getnetworkinfo.connections`
+
+Points are written:
+
+- On each `/api/dashboard/summary` request.
+- In a background sampler loop at configured interval.
+
+## Settings Defaults
+
+Default values used when no persisted row exists:
+
+- `rpc_url`: `http://127.0.0.1:8332`
+- `rpc_username`: empty string
+- `rpc_password`: empty string
+- `rpc_wallet`: empty string
+- `config_path`: empty string
+- `ssh_host`: empty string
+- `ssh_port`: `22`
+- `ssh_username`: empty string
+- `ssh_password`: empty string
+- `ssh_key_path`: empty string
+- `bitcoin_binary`: `bitcoind`
+- `updated_at`: empty string
+
+## Data Consumers
+
+- `/api/settings` and `/api/settings` (PUT) read and write `node_settings`.
+- `/api/dashboard/history*` reads `metrics_history`.
+- `/api/dashboard/summary` and sampler thread write `metrics_history`.
+
+See `doc/api.md` for endpoint-level contracts.