Initial commit

doc/architecture.md

@@ -0,0 +1,98 @@
+# Architecture
+
+## Overview
+
+The project is a single-service web application that provides operational control and observability for a remote Bitcoin Core node.
+
+Core runtime components:
+
+- FastAPI server for UI and API delivery.
+- Session-based authentication middleware.
+- SQLite persistence for node settings and sampled metrics.
+- Bitcoin Core JSON-RPC client for node data and RPC execution.
+- SSH command runner for daemon start and restart operations.
+- Vanilla JavaScript frontend with Chart.js visualizations.
+
+Related references:
+
+- API contracts: `doc/api.md`
+- Persistence schema: `doc/data-models.md`
+- Deployment rules: `doc/build-and-deploy.md`
+
+## Component Boundaries
+
+### Backend Modules
+
+- `app/main.py`
+  - Composes FastAPI app, middleware, startup/shutdown hooks, and all route handlers.
+  - Validates payloads via Pydantic models.
+  - Aggregates dashboard summary data and persists metric samples.
+  - Starts a background sampler thread that periodically stores metrics.
+- `app/auth.py`
+  - Verifies login credentials.
+  - Enforces authenticated API access through `require_auth`.
+- `app/config.py`
+  - Loads and validates environment-driven runtime configuration.
+  - Creates the data directory when needed.
+- `app/db.py`
+  - Initializes schema.
+  - Persists and reads node settings.
+  - Persists and reads metric history with retention trimming.
+- `app/bitcoin_rpc.py`
+  - Encapsulates JSON-RPC request and batch request behavior.
+  - Normalizes RPC errors through `BitcoinRPCError`.
+  - Parses `help` output into command catalog entries.
+- `app/ssh_control.py`
+  - Resolves SSH host and connection parameters.
+  - Executes remote commands and returns execution result payloads.
+  - Builds safe daemon start command strings.
+
+### Frontend Assets
+
+- `app/templates/index.html`
+  - Declares login, dashboard, settings modal, control actions, and RPC explorer regions.
+- `app/static/app.js`
+  - Owns client state, auth transitions, API calls, chart hydration, and polling.
+  - Caches metric history in browser local storage.
+- `app/static/styles.css`
+  - Provides responsive layout and UI styling.
+
+## Runtime Flow
+
+1. Application startup calls `init_db()` and starts the metrics sampler thread.
+2. Browser loads `/`, then frontend checks `/api/auth/me`.
+3. After login, frontend loads settings, RPC command catalog, history, and summary.
+4. Frontend refreshes summary every 15 seconds while page is open.
+5. Backend stores sampled metrics:
+- on each summary API call.
+- in the background sampler at `METRICS_SAMPLER_INTERVAL_SECONDS` cadence.
+
+## Data and Control Paths
+
+- Read-only node visibility:
+  - `/api/dashboard/summary` uses batch RPC to fetch chain, network, mempool, mining, and uptime data.
+  - `/api/dashboard/history` and `/api/dashboard/history/{window}` read persisted metric points.
+- Node management:
+  - Stop uses Bitcoin RPC `stop`.
+  - Start uses SSH execution of `bitcoind -daemon -conf=<config_path>`.
+  - Restart attempts RPC stop, waits briefly, then uses SSH start.
+- RPC explorer:
+  - Command catalog derives from `help` output.
+  - Arbitrary RPC call endpoint accepts method and JSON-array params.
+
+## Error and Resilience Model
+
+- `BitcoinRPCError` and `SSHControlError` are mapped to HTTP `502`.
+- Missing required node settings are surfaced as HTTP `400`.
+- Validation issues return HTTP `422`.
+- Background sampler is best-effort and suppresses internal exceptions to avoid service interruption.
+
+## Security Model
+
+- Authentication is session-cookie based using `SessionMiddleware`.
+- Access to operational endpoints requires `Depends(require_auth)`.
+- Credential verification supports:
+  - plaintext password via `APP_PASSWORD`
+  - bcrypt hash via `APP_PASSWORD_HASH`
+
+See `doc/environment.md` for security-relevant configuration fields.