From 7280f1dfeaabfbe5d363dd352bbfff49ab54bb28 Mon Sep 17 00:00:00 2001 From: JC Date: Tue, 28 Jul 2026 17:22:03 +0000 Subject: [PATCH] docs: add product guide --- docs/PRODUCT.md | 377 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 377 insertions(+) create mode 100644 docs/PRODUCT.md diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md new file mode 100644 index 0000000..a15c8c3 --- /dev/null +++ b/docs/PRODUCT.md @@ -0,0 +1,377 @@ +# MinerOps Product Guide + +## Purpose + +MinerOps is intended to become the self-hosted operational system of record for +cryptocurrency mining operations. + +Its primary product position is: + +> The self-hosted operating system for cryptocurrency mining operations. + +Its supporting statement is: + +> Know every miner. Track every repair. Control every rack. + +"Operating system" describes a shared operational foundation, not a replacement +for a computer operating system or miner firmware. MinerOps is intended to +connect the records and workflows that operators use to understand their fleet, +maintain equipment, and coordinate work. + +"Know every miner" means that each asset should have a durable, understandable +record. "Track every repair" means that failures, work, parts, tests, and +outcomes should remain connected to that record. "Control every rack" means +that operational actions should be available with appropriate context, +permissions, safeguards, and visibility. + +**Current implementation:** MinerOps is an early-stage application. The +repository contains authentication and role foundations, an Inventory schema +and backend domain foundation, and existing operational workflows for areas such +as discovery, repairs, locations, monitoring, and control. These areas are not +all complete or organized as finished product domains. + +**Product direction:** MinerOps should bring these capabilities together around +one durable operational record while remaining practical for self-hosted use. +The directions in this guide are not claims that every capability is currently +implemented. + +## Target Users + +MinerOps is intended for people responsible for operating and maintaining +cryptocurrency mining equipment, including: + +- Mining farm operators +- Technicians +- Operations managers +- Site administrators +- Owners managing small or medium fleets +- Organizations operating multiple rooms or sites + +These users need different levels of visibility and control. A technician may +need fast access to asset history and repair context from the floor. A manager +may need fleet state, work status, and accountability across teams. A site +administrator may need configuration and access controls. An owner may need a +clear view across one facility or several sites. + +MinerOps should support those different working contexts without forcing every +user to navigate the same amount of detail or receive the same operational +control. Detailed permissions belong to access-control design rather than this +product guide. + +## Problems MinerOps Solves + +Mining operations often build their working record from several disconnected +sources. Asset details may live in spreadsheets, current health in monitoring +tools, repair notes in informal documents, and physical location knowledge in a +technician's memory. + +Common operational problems include: + +- Asset information spread across spreadsheets and ad hoc records. +- IP addresses changing without a reliable link to the durable asset. +- Control board replacements changing MAC addresses and confusing identity. +- Repair and maintenance history being incomplete or difficult to find. +- Equipment being difficult to locate across rooms, racks, shelves, or storage. +- Important fleet knowledge existing only in individual technicians' memories. +- Monitoring and control tools being disconnected from inventory and repair + records. +- Limited audit history for changes and operational actions. +- Uncertainty about which miners are active, spare, under repair, missing, or + retired. +- Difficulty coordinating safe actions across many miners at once. + +MinerOps is intended to reduce this fragmentation. It should help operators +answer practical questions about what an asset is, where it is, what condition +it is in, what has happened to it, and what action is appropriate next. + +## Product Vision + +The long-term product direction is one self-hosted platform connecting: + +- Inventory +- Durable asset identity +- Network discovery +- Locations +- Repairs and work orders +- Spare parts +- Monitoring and telemetry +- Alerts +- Fleet control +- Scheduling and automation +- Electrical and infrastructure records +- Historical reporting +- Audit history + +These capabilities should reinforce one another. A monitoring alert should +point to the correct asset. A repair should include the relevant history and +location. A component replacement should not erase the identity of the miner. A +fleet action should respect maintenance state and leave an audit record. + +This list defines product direction. The repository contains foundations and +working early-stage workflows in several of these areas, but it does not yet +provide the complete product described here. + +## Product Principles + +### Single Source of Truth + +Important operational records should have one authoritative home. Other tools +may contribute observations or consume data, but MinerOps should reduce the +need to reconcile competing spreadsheets, notes, and dashboards. + +A source of truth must be understandable and correctable. It should make the +current record clear while retaining enough history to explain how that record +changed. + +### Asset Identity Before Network Identity + +A miner is not defined by its current IP address or MAC address. Network values +are mutable observations about an asset, not the asset's durable identity. + +MinerOps should preserve a stable internal identity through address changes, +control board replacements, movement, repair, storage, and retirement. Network +identity remains important, but it must be associated with the asset rather +than substituted for it. + +### Preserve History + +Operationally important changes should remain traceable instead of silently +overwriting the past. Repairs, locations, network identities, components, +status changes, and operator actions may all affect how an asset's current state +is understood. + +History should be useful rather than merely accumulated. Records need clear +timestamps, context, and attribution where appropriate. + +### Self-Hosted First + +Operators should retain control of their operational data and deployment. +MinerOps should work as software that an organization can run within its own +environment without requiring a mandatory hosted subscription. + +Self-hosted first does not prohibit internet access, remote access, or external +integrations. Those capabilities should remain deliberate choices under the +operator's control. + +### Safe by Default + +MinerOps may coordinate actions that interrupt mining or affect many devices. +Potentially disruptive actions require deliberate authorization, clear scope, +validation, and auditability. + +Defaults should favor observation and review over unexpected action. A new +installation or development environment should not begin issuing broad or +destructive commands without explicit configuration. + +### Practical Operations Over Cryptocurrency Hype + +MinerOps is an operations and infrastructure product. Its value comes from +making assets, repairs, locations, health, and controls easier to understand and +manage. + +It is not a trading, investment, or promotional product. Product decisions +should be evaluated against operational usefulness rather than cryptocurrency +trends or speculative features. + +### Technician-Friendly + +Common workflows should be usable where the work happens. Interfaces should +support clear scanning, direct actions, and responsive layouts suitable for +phones and workstations. + +Mobile and QR-assisted workflows are appropriate product directions when they +reduce lookup time or data-entry mistakes. They should complement durable asset +identity rather than introduce a separate record. + +### Progressive Complexity + +A small operator should be able to begin with useful inventory, location, and +repair workflows without configuring every advanced capability. Larger or more +complex installations should be able to add structure as their needs grow. + +Advanced monitoring, automation, infrastructure mapping, and integrations +should not make the basic operational record harder to use. + +### Explicit Human Control + +Automation should assist operators without making important decisions +invisible. Users should understand what will happen, what is happening, and what +happened afterward. + +Automated behavior should expose its scope, conditions, limits, and result. An +operator must be able to distinguish intentional automation from an unexpected +system action. + +## Core Product Areas + +### Inventory and Assets + +Inventory provides durable records for miners and related hardware. It connects +operator-facing Asset IDs, hardware identifiers, lifecycle state, tags, notes, +and ownership of the asset record without relying on current network values. + +### Identity and Discovery + +Identity and discovery connect observations from the network to stable assets. +The product should distinguish current network information from history and +provide deliberate handling when components or identities change. + +### Locations and Infrastructure + +Locations and infrastructure describe where equipment is installed or stored +and how it relates to sites, rooms, racks, shelves, positions, and electrical +context. Movement should remain understandable over time. + +### Repairs and Maintenance + +Repairs and maintenance connect problems, diagnostics, work, parts, testing, +and return-to-service outcomes to the asset. Technicians should be able to see +prior work before beginning another repair. + +### Monitoring and Alerts + +Monitoring and alerts explain live and historical operational health. They +should add observations to the operational record without replacing durable +inventory, repair, or lifecycle information. + +### Fleet Operations + +Fleet operations provide permission-controlled actions for individual miners or +groups. Controls should include enough identity, location, health, and +maintenance context to reduce avoidable mistakes. + +### Scheduling and Automation + +Scheduling and automation support repeatable work while preserving safeguards, +expiry, rollback or recovery behavior where practical, and operator visibility. +Automation should make coordinated operations more predictable, not less +accountable. + +### Reporting and Audit History + +Reporting and audit history help operators understand what changed, who changed +it, why it changed, and what happened over time. Reports should draw from the +same operational records used by day-to-day workflows. + +## Operational Source of Truth + +MinerOps should connect information that is commonly separated: + +- Asset identity +- Network identity +- Physical location +- Repair status +- Operational status +- Historical changes + +These are related views of one operational asset, not independent records to be +manually reconciled. Current status should remain distinct from lifecycle, +repair, and location state so that one value does not erase important context. + +A miner should remain understandable throughout its lifecycle: initial entry, +deployment, discovery, movement, component replacement, failure, repair, +testing, storage, redeployment, and retirement. Operators should be able to +follow that history even when the miner's address, control board, rack, or +condition changes. + +The source-of-truth role also requires correction. Authorized users should be +able to fix inaccurate records without destroying meaningful history or hiding +who made the change. + +## Self-Hosted Philosophy + +Self-hosting matters because mining operations depend on local equipment, +segmented networks, and operational data that may need to remain under direct +organizational control. + +A self-hosted MinerOps deployment should support: + +- Operational control over configuration and availability. +- Ownership of asset, repair, telemetry, and audit data. +- Access to equipment on local networks where appropriate. +- Independence from mandatory hosted subscriptions. +- Operation in restricted or segmented environments. +- Backup, restore, and migration under the operator's control. + +Self-hosted does not mean isolated. Optional remote access, manufacturer +interfaces, reporting systems, or other integrations may be valuable. They +should not make a hosted third party the mandatory owner of the operational +record. + +## Safety and Control + +MinerOps may eventually perform actions capable of disrupting individual miners +or a significant part of a fleet. Safety is therefore a product behavior, not +only an implementation concern. + +Product expectations include: + +- Role and permission enforcement. +- Clear confirmation for destructive or broad actions. +- Dry-run or preview behavior where practical. +- Staggering, rate limits, and scope limits for bulk actions. +- Commands that expire rather than remain indefinitely actionable. +- Audit history for requested actions and outcomes. +- Awareness of maintenance state and intentionally offline equipment. +- Safe defaults in development and new installations. + +The interface should communicate the intended target, scope, and likely impact +before an action is accepted. Afterward, the operator should be able to see +whether the action ran, partially succeeded, failed, expired, or was cancelled. + +Automation does not remove the need for authorization or visibility. The +broader the potential effect, the more explicit the safeguards should be. + +## What MinerOps Is Not + +MinerOps is not intended to be: + +- A cryptocurrency exchange +- A wallet +- A trading platform +- An investment dashboard +- A hosted mining provider +- A replacement for manufacturer firmware +- A general-purpose data centre management suite +- A tool that hides unsafe automation from operators +- A promotional cryptocurrency project + +MinerOps may integrate with manufacturer interfaces, accounting systems, +monitoring tools, or other external services when those integrations improve +mining operations. Integration does not change the product's core purpose: a +self-hosted operational system of record for mining assets and workflows. + +## Measures of Success + +MinerOps is succeeding when: + +- Operators can identify and locate any recorded miner quickly. +- A miner's history remains understandable after IP, MAC, control board, or + location changes. +- Technicians can see prior failures and repairs before starting work. +- Managers can understand fleet state without reconciling several spreadsheets. +- Bulk actions are controlled, visible, and auditable. +- Operational data can be backed up, restored, and migrated. +- The system remains useful for both small and larger installations. +- New features strengthen a coherent operational record instead of creating + another disconnected tool. + +These are practical outcomes rather than numerical targets. Measures should be +refined using real operator workflows and evidence as the product develops. + +## Product Decision Test + +A proposed feature should normally answer yes to one or more of these questions: + +- Does it help identify a miner or related asset? +- Does it help locate equipment? +- Does it improve understanding of current or historical condition? +- Does it support repair, maintenance, or return-to-service work? +- Does it improve safe monitoring or control? +- Does it preserve meaningful operational history? +- Does it reduce fragmented or duplicated records? +- Does it remain consistent with self-hosting and operator control? + +A technically interesting feature is not automatically a MinerOps feature. It +should improve cryptocurrency mining operations and fit the product's +source-of-truth role.