minerops/docs/PRODUCT.md

# 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.