# Conventions and Coding Patterns

This document defines repository conventions to preserve existing architecture and behavior.

## Module Boundaries

- Keep backend concerns separated by module:
  - auth in `app/auth.py`
  - configuration in `app/config.py`
  - persistence in `app/db.py`
  - RPC transport in `app/bitcoin_rpc.py`
  - SSH control in `app/ssh_control.py`
  - route composition in `app/main.py`
- Do not collapse these responsibilities into one file.

## API and Error Patterns

- Protected routes must use `Depends(require_auth)`.
- Domain errors should raise module-specific exceptions:
  - `BitcoinRPCError`
  - `SSHControlError`
- Domain exceptions are converted to HTTP `502` in centralized exception handlers.
- Input validation should use Pydantic models and explicit HTTP errors for invalid state.

## Persistence Patterns

- Access SQLite through `app/db.py` helpers.
- Keep node settings as a single upserted row with `id = 1`.
- Preserve metrics retention behavior:
  - 30-day time window
  - 20000 row cap

## Frontend Patterns

- Keep frontend implementation in vanilla JavaScript plus Chart.js.
- Maintain centralized client `state` object in `app/static/app.js`.
- Use existing API helpers (`api`, error handling, auth transitions).
- Keep responsive behavior aligned with current CSS breakpoints.

## Security and Operational Patterns

- Require authentication for all state-changing and node-control APIs.
- Keep SSH command composition shell-safe using quoting.
- Treat background sampling as best-effort to avoid impacting request flow.

## Documentation and Change Tracking

When behavior, contracts, or operations change:

1. Update affected docs in `/doc`.
2. Update `README.md` if repository landing information changes.
3. Record meaningful changes in `CHANGELOG.md` under `[Unreleased]`.

Reference index: `doc/README.md`.