tellscoin/doc/architecture.md

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.