diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..70d5eb6 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,229 @@ +# MinerOps Roadmap + +## Purpose + +This roadmap communicates the intended direction of MinerOps from its current +early-stage foundation toward a production-ready, self-hosted mining operations +platform. It describes broad development phases, their priorities, and why work +is ordered that way. + +The roadmap is not detailed project scheduling. It does not assign dates, +promise delivery order within a phase, or replace the work needed to define and +validate individual features. Priorities may change as operational experience +and operator feedback reveal better sequencing. + +The architectural rules in `ARCHITECTURE.md`, product principles in +`PRODUCT.md`, and recorded decisions in `DECISIONS.md` take precedence over +roadmap speed. A milestone should move more slowly rather than weaken durable +identity, history, safety, testability, or domain ownership. + +## Current Status + +MinerOps currently has an early-stage backend and operational application, +containerized development services, PostgreSQL and Redis infrastructure, and a +versioned Alembic schema. Authentication, login gating, and role foundations are +implemented. + +The Inventory domain has a database schema, Pydantic models, domain exceptions, +a service, a PostgreSQL repository, and focused automated tests. It is not yet +exposed through a new domain HTTP API. Existing application code also contains +working early-stage workflows for discovery, repairs, locations, telemetry, and +control, but those areas are not complete product domains and remain in the +integrated application module. + +The repository now includes established branding and primary guides for product, +architecture, and long-lived decisions. The project remains in the Foundation +phase. + +## Guiding Principles + +Roadmap ordering follows these principles: + +- **Stable foundations before features:** Identity, schema, access control, and + test boundaries must support later workflows rather than be repaired after + every expansion. +- **Durable operational records before automation:** MinerOps must know which + asset, location, condition, and history an action affects before automating + that action. +- **Safety before convenience:** Controls and broad actions require permissions, + clear scope, safeguards, and auditability. +- **Incremental delivery:** Working behavior is preserved while features move + behind explicit domain boundaries in reviewable steps. +- **Maintainability over rapid expansion:** New capability should strengthen the + shared operational record instead of creating another isolated workflow. + +These principles describe how phases are evaluated. They do not require every +capability in one phase to be exhausted before useful work in another phase can +begin. + +## Development Phases + +### Phase 1: Foundation + +**Status: Current phase.** + +Foundation establishes the application, authentication and role model, database +migration authority, initial Inventory domain, repeatable development stack, +focused tests, branding, and primary project documentation. + +The purpose of this phase is to create stable ownership and validation before +adding more product surface. Inventory is the first reference domain because +asset records are needed by identity, repair, monitoring, and control workflows. +Phase 1 is complete only when the foundations are usable as dependencies for +subsequent domain work, not merely present as isolated code. + +### Phase 2: Inventory & Identity + +**Status: Planned direction.** + +This phase completes the core asset record and connects it to discovery and +network observations. It develops practical asset workflows around stable +internal identity, operator-facing Asset IDs, lifecycle state, tags, notes, and +location relationships. + +Discovery should resolve observations to durable assets without defining an +asset by its current IP or MAC address. Network identity history and deliberate +handling of address or control board changes preserve continuity. Inventory +becomes the dependable source that later operational domains can reference. + +This phase precedes deeper repair and control work because those workflows must +act on the correct asset and retain context through component, network, and +location changes. + +### Phase 3: Operations + +**Status: Planned direction.** + +This phase develops day-to-day technician and operations workflows around the +durable asset record. Repairs, maintenance, work orders, parts usage, equipment +movement, testing, and return-to-service history become coherent operational +records rather than disconnected actions. + +Technician experience is a priority. Responsive and QR-assisted workflows may +reduce lookup and data-entry effort where they reinforce the same asset record. +Existing repair and location behavior should move incrementally into clear +domain ownership while preserving working use cases. + +Operations follows Inventory and Identity so every repair, part, and movement +has stable ownership and useful history. + +### Phase 4: Monitoring + +**Status: Planned direction.** + +This phase connects telemetry, alerts, fleet health, and historical trends to +the operational record. Monitoring should explain current and historical +condition without replacing lifecycle, repair, location, or maintenance state. + +Alerts become more useful when they can account for asset identity, known +maintenance, intended downtime, location, and prior behavior. Historical trends +should help operators recognize persistent or recurring problems rather than +serve as an isolated stream of measurements. + +Monitoring follows core operational records so observations carry enough +context to support decisions and avoid treating expected conditions as unknown +failures. + +### Phase 5: Fleet Control + +**Status: Planned direction.** + +This phase develops controlled actions for individual miners and groups, then +extends them toward scheduling and automation. Permissions, confirmation, +scope, staggering, expiry, maintenance awareness, and audit history are product +requirements rather than optional polish. + +Bulk operations should remain visible before, during, and after execution. +Automation must preserve explicit human control and distinguish planned actions +from unexpected device behavior. + +Fleet control follows identity, operations, and monitoring because safe action +requires confidence in the target, awareness of maintenance state, and feedback +about the result. + +### Phase 6: Infrastructure + +**Status: Planned direction.** + +This phase deepens the model of sites, rooms, racks, positions, electrical +relationships, power, and capacity. It connects miners and operational state to +the physical constraints under which a mining facility runs. + +Earlier phases may use basic location relationships. Phase 6 develops the wider +infrastructure record needed for capacity planning, movement decisions, and +understanding how equipment relates to power and space. + +Infrastructure depth should remain progressively adoptable. A small installation +should not need to model every electrical relationship before basic Inventory +or Operations workflows are useful. + +### Phase 7: Production Readiness + +**Status: Planned direction.** + +This phase prepares MinerOps for sustained operation and supported upgrades. It +focuses on performance, broader automated testing, API consistency, complete +operator and deployment documentation, reliable upgrade paths, backup and +restore procedures, deployment hardening, observability, and long-term support +practices. + +Production readiness applies across all product areas. It includes verifying +failure behavior, recovery, data migration, and operational maintenance rather +than only completing feature surfaces. + +This phase is placed after the principal product domains so readiness work can +be measured against realistic workflows. Reliability, upgrade safety, and +observability remain ongoing concerns in every earlier phase rather than being +deferred entirely to the end. + +## Future Opportunities + +Possible areas for later exploration include additional external integrations, +manufacturer APIs, richer reporting, operational analytics, mobile workflow +improvements, and a plugin architecture if multiple real integrations justify a +stable extension boundary. + +These are opportunities, not commitments. They should be evaluated against the +product decision test, self-hosted ownership, safety, maintenance cost, and the +need to preserve one coherent operational record. + +## How Priorities Change + +Priorities may change in response to operator feedback, experience from real +mining operations, reliability findings, safety concerns, maintenance cost, or +new operational requirements. A newly discovered data-integrity or safety need +may appropriately move ahead of a visible feature. + +Changes to priority should be explained using the product principles and ADRs. +Reordering is appropriate when it improves the product without weakening stable +identity, history, operator control, or architectural boundaries. A roadmap +change does not silently reverse a long-lived decision; such a change requires a +new documented decision. + +## Completed Milestones + +Major completed foundations include: + +- Repository and containerized development foundation +- PostgreSQL, Redis, and Alembic migration foundation +- Authentication, login gating, and role foundation +- Manual Inventory schema and backend domain foundation +- Focused Inventory and migration test foundations +- MinerOps branding package and project README +- Architecture guide +- Product guide +- Architecture and Product Decision Records + +Completion here means the named foundation exists in the repository. It does not +mean every product workflow associated with that area is complete. + +## Reading This Roadmap + +The roadmap communicates intended direction rather than guaranteed delivery +order. Features may move between phases when doing so improves the overall +product without weakening the architectural, product, or safety principles +established elsewhere. + +Use phases to understand dependency and priority, not as fixed release promises. +Evaluate actual work against current operational needs and the durable decisions +recorded in the project documentation.