Initial commit

doc/conventions.md

@@ -0,0 +1,54 @@
+# 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`.