docs: add project roadmap

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.