tellscoin/doc/conventions.md

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.