55 lines
1.8 KiB
Markdown
55 lines
1.8 KiB
Markdown
# 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`.
|