minerops/ARCHITECTURE.md

MinerOps Target Architecture

MinerOps will move from its current working checkpoint toward a modular operations platform without a big-bang rewrite. Every milestone must leave the production application deployable and preserve verified workflows.

Boundaries

• The hub owns users, authorization, fleet inventory, repairs, locations, reporting, command policy, audit history, and long-term telemetry.
• Site agents own network-local discovery, polling, and miner command execution.
• The hub must not require a route to miner VLANs.
• WhatsMiner protocols are adapters behind one capability-based interface.

Backend

The target backend is organized into FastAPI routers, domain services, and database repositories for:

• identity and access
• fleet inventory
• telemetry and retention
• repairs and parts
• locations
• agents and command queues
• WhatsMiner protocol capabilities
• system health

Alembic is the only authority for persistent schema changes. Runtime table creation remains temporarily for backward compatibility and will be removed after migrations and tests cover every current path.

Frontend

The target frontend is a typed, responsive application with a shared design system. Authentication is established before protected pages render. Views adapt to desktop, tablet, and phone layouts and expose actions according to server-enforced permissions.

Identity

MinerOps application accounts are distinct from WhatsMiner device accounts. The default application roles will be Admin, Manager, Technician, and Read Only. Authorization is permission-based and enforced by backend endpoints.

Safety

• Scanning and real controls are disabled by default in development.
• Site-agent commands are authenticated, durable, expiring, idempotent, and audited.
• Destructive operations support dry-run behavior and explicit authorization.
• Protocol adapters are tested with sanitized fixtures before real controls are enabled.

Migration Order

1. Reproducible schema and development baseline.
2. Accounts, roles, secure sessions, and login gate.
3. Responsive application shell and shared UI components.
4. Optimized dashboard loading.
5. WhatsMiner 4028 and 4433 protocol adapters.
6. Incremental extraction of repairs, locations, agents, commands, and health from the legacy application module.