-MinerOps is a self-hosted mining fleet operations console for tracking, repairing, locating, and controlling WhatsMiner ASICs.
+
MinerOps
-## Current deployment
+
+ The self-hosted operating system for cryptocurrency mining operations.
+
+ Know every miner. Track every repair. Control every rack.
+
-- Hub CT: 306
-- Public URL: https://plexus.lussier.cc
-- Repository: https://gitea.lussier.cc/lussierj/minerops
-- Backend container: minerops-backend
-- Database container: minerops-postgres
-- Redis container: minerops-redis
+## Overview
-## Main pages
+MinerOps is a self-hosted platform intended to provide one authoritative source
+of truth for cryptocurrency mining operations. It is being built to connect
+asset records, network identity, repair history, physical location, telemetry,
+and operational controls without depending on a hosted management service.
-- /dashboard - fleet dashboard and repair summary
-- /repairs - repair queue, notes, parts used, history, CSV export
-- /locations - room/rack/shelf location map
-- /system-health - app, database, table size, route, and retention health
+The repository contains a working early-stage application and the first
+foundations of a more modular architecture. Current development is focused on
+turning those foundations into well-defined product domains with tested service
+and persistence boundaries.
-## Repair workflow
+The longer-term product direction combines:
-1. Open /repairs.
-2. Find the miner by MAC, IP, model, serial, or problem.
-3. Add repair notes.
-4. Select parts used and quantity.
-5. Update repair status.
-6. Use History to edit or delete mistaken entries.
-7. Mark Ready to Shelf or use Move to Shelf.
-8. Return the miner to an open shelf position on /locations.
+- Miner inventory
+- Network discovery and identity tracking
+- Repairs and maintenance
+- Locations and electrical infrastructure
+- Monitoring and alerts
+- Fleet control
+- Scheduling and automation
+- Historical records and reporting
-## Repair statuses
+These areas describe the product direction, not a claim that every workflow is
+complete or ready for production use.
-- Open
-- Diagnosing
-- Waiting Parts
-- In Progress
-- Testing
-- Ready to Shelf
-- Needs Follow-up
-- Completed
-- Failed
-- Cancelled
+## Why MinerOps?
-## Retention
+Mining operations often accumulate several partial versions of the truth:
+spreadsheets for assets, separate monitoring tools for performance, informal
+repair notes, and location knowledge held by individual technicians.
-Retention is currently scheduled in dry-run mode.
+That fragmentation becomes harder to manage when IP addresses change, control
+boards or network interfaces are replaced, equipment moves between racks, and
+repair history is incomplete. MinerOps is intended to give operators one
+self-hosted operational record that follows each miner through its full
+lifecycle.
-Current intended policy:
+## Core Capabilities
-- Raw status snapshots: 30 days
-- Hourly rollups: 1 year or longer
-- Daily rollups: long term
-- Repair, location, and MAC history: permanent
+### Asset and Inventory Management
-Verify /system-health before switching retention to apply mode.
+Maintain stable asset records independently of a miner's current IP address.
+The inventory schema and backend domain foundation currently support Asset IDs,
+hardware identifiers, lifecycle state, tags, notes, location references, and
+seen timestamps. Inventory HTTP APIs and product workflows are the next
+application milestone.
-## Common commands
+### Miner Identity and Discovery
-Health check:
+Associate changing network information with durable miner records. Existing
+code includes discovery and network identity foundations; formal identity
+history and transfer workflows remain planned work.
-pct exec 306 -- bash -lc "curl -s http://127.0.0.1:8000/api/health"
+### Repairs and Maintenance
-Rebuild backend:
+Build a complete service history around each miner, including repair status,
+notes, parts, and return-to-service workflows. Operational repair functionality
+exists today, while extraction into a dedicated domain architecture is still
+planned.
-pct exec 306 -- bash -lc "cd /opt/minerops && docker compose build backend || docker-compose build backend"
-pct exec 306 -- bash -lc "cd /opt/minerops && docker compose up -d --force-recreate backend || docker-compose up -d --force-recreate backend"
+### Locations and Infrastructure
-Check logs:
+Track where equipment is installed and relate miners to sites, rooms, racks,
+shelves, and operational infrastructure. Existing location workflows will be
+refined as the modular architecture develops.
-pct exec 306 -- bash -lc "docker logs minerops-backend --since 30m"
+### Monitoring and Health
-Git status:
+Collect miner status and telemetry, identify stale or unhealthy equipment, and
+support operational health views. The repository contains current telemetry and
+retention foundations; broader alerting remains planned.
-pct exec 306 -- bash -lc "cd /opt/minerops && git status --short"
+### Fleet Operations
-## Safe local development
+Provide controlled fleet actions while keeping command policy, authorization,
+and site-local execution explicit. Existing command workflows are under active
+development and should not be treated as a finished control platform.
-Development uses a separate Compose project, database volume, Redis volume, and
-localhost-only backend port. It does not reuse the production `.env` file.
-Scheduled scanning and real miner power/reboot controls are disabled.
+### Automation and Scheduling
-First-time setup:
+Coordinate recurring scans, scheduled actions, retention, and other repeatable
+operations. Scheduling and automation will expand after the core inventory and
+identity domains are established.
-```bash
-./scripts/dev-env-init.sh
-docker compose --env-file .env.dev -f compose.dev.yaml up -d --build
+### Audit History and Reporting
+
+Preserve important operational changes and support practical reporting across
+assets, repairs, locations, and fleet activity. Audit-log and reporting
+foundations exist; the complete reporting model remains planned.
+
+## Current Status
+
+MinerOps is under active development.
+
+**Current development stage:** `v0.2 - Foundation`
+
+Verified foundations in the repository include:
+
+- Docker-based development environment
+- PostgreSQL data store
+- Redis service
+- Alembic schema migrations
+- Session-based authentication and login gating
+- Admin, Manager, Technician, and Read Only role foundations
+- Manual miner inventory database schema
+- Inventory Pydantic models
+- Inventory repository and service domain foundation
+- Automated repository and service tests for the Inventory domain
+- Disposable development baseline tests
+
+**Next application milestone:** `v0.3 - Inventory`
+
+**Next technical feature:** Inventory API
+
+## Architecture
+
+MinerOps is moving toward a modular backend with deliberate separation between
+transport, business rules, and persistence:
+
+```text
+Frontend
+ |
+ v
+FastAPI routers
+ |
+ v
+Domain services
+ |
+ v
+Repositories
+ |
+ v
+PostgreSQL
```
-Verify the environment:
+FastAPI routers will own HTTP request and response concerns. Domain services
+will own operational rules and orchestration. Repositories will own database
+access. The Inventory domain is the first backend area established with these
+boundaries; other working application areas are still being migrated
+incrementally.
-```bash
-docker compose --env-file .env.dev -f compose.dev.yaml ps
-curl --fail --silent http://127.0.0.1:18000/api/health
-```
+## Technology Stack
-Run the disposable clean-database baseline:
+Current technologies:
-```bash
-./scripts/test-dev-baseline.sh
-```
+- Python
+- FastAPI
+- Pydantic
+- PostgreSQL
+- Alembic
+- Redis
+- Docker and Docker Compose
+- Nginx development gateway
-The baseline uses a separate Compose project and port, verifies migrations,
-schema, pages, retention rollups, and safety interlocks, then deletes only its
-own temporary volumes.
+A typed, responsive frontend with a shared design system is planned. Its
+technology selection has not yet been finalized in this repository.
-Stop development services without deleting their data:
+## Roadmap
-```bash
-docker compose --env-file .env.dev -f compose.dev.yaml down
-```
+- `v0.2 - Foundation`
+- `v0.3 - Inventory`
+- `v0.4 - Identity`
+- `v0.5 - Operations`
+- `v0.6 - Monitoring`
+- `v0.7 - Automation`
+- `v1.0 - Production Ready`
-The generated `.env.dev` file is mode `0600` and ignored by Git. To use a
-different local port, change `MINEROPS_DEV_PORT` in `.env.dev`.
+Roadmap scope and release boundaries may evolve as development continues and
+operational requirements become clearer.
-## Safety notes
+## Documentation
-- Do not commit .env.
-- Do not commit backups, logs, database dumps, imports, or runtime data.
-- Do not enable scanning or real miner controls in the development environment.
-- Check /system-health after major changes.
-- Commit and push after each stable working change.
+Detailed product, architecture, development, database, testing, and roadmap
+documentation will live under `docs/`. That documentation set is still being
+developed, so this README does not link to files that do not yet exist.
+
+## Contributing
+
+MinerOps is in early development. Contribution guidelines will be added as the
+architecture, development workflow, and review expectations stabilize.
+
+## License
+
+The MinerOps license has not yet been finalized. No license file is currently
+included in this repository.
diff --git a/branding/BRANDING.md b/branding/BRANDING.md
new file mode 100644
index 0000000..1cbed0e
--- /dev/null
+++ b/branding/BRANDING.md
@@ -0,0 +1,111 @@
+# MinerOps Brand Guidelines
+
+## Brand Position
+
+MinerOps is practical infrastructure for operators who need a clear, reliable
+view of mining assets, repairs, locations, and controls. The identity should
+feel precise, capable, and built for daily engineering work.
+
+Primary tagline:
+
+> The self-hosted operating system for cryptocurrency mining operations.
+
+Secondary tagline:
+
+> Know every miner. Track every repair. Control every rack.
+
+## Branding Philosophy
+
+- **Operational clarity:** Prefer direct language, strong hierarchy, and
+ purposeful visual elements.
+- **Engineering confidence:** Use measured geometry, consistent spacing, and
+ restrained color.
+- **Self-hosted independence:** Present MinerOps as dependable infrastructure
+ owned and controlled by its operator.
+- **Human utility:** Keep the identity approachable and readable without
+ becoming playful or ornamental.
+
+## Logo System
+
+The MinerOps mark combines a geometric hexagon with an angular letter M. The
+hexagon suggests infrastructure, modular systems, and engineered hardware. The
+M creates immediate product recognition.
+
+Available placeholders:
+
+- `logo.svg`: Primary mark for general use.
+- `logo-light.svg`: Navy and orange mark for light backgrounds.
+- `logo-dark.svg`: White and orange mark for dark backgrounds.
+- `favicon.svg`: Compact filled mark optimized for small sizes.
+- `wordmark.svg`: Symbol paired with the MinerOps name.
+
+Use the supplied artwork without changing its proportions, stroke weights, or
+relative colors. Do not rotate, skew, outline, add effects, or place the mark
+inside another shape. Do not use gradients.
+
+## Clear Space
+
+Maintain clear space around the logo equal to at least one quarter of the
+mark's width. For the wordmark, use the hexagon's internal margin as the
+minimum clear space on every side.
+
+Recommended minimum sizes:
+
+- Standalone logo: 24 px digital, 8 mm print.
+- Wordmark: 120 px digital, 32 mm print.
+- Favicon: 16 px digital.
+
+## Wordmark Usage
+
+Use the wordmark when the audience needs explicit product identification, such
+as documentation covers, sign-in screens, repository graphics, and event
+materials. Use the standalone mark where MinerOps is already named nearby or
+space is limited.
+
+Keep `Miner` in Miner Navy or White and `Ops` in Ops Orange. Do not alter the
+capitalization or insert a space between the words.
+
+## Typography
+
+Recommended interface and brand typefaces:
+
+1. **Inter:** Primary choice for user interfaces, documentation, and marketing
+ copy.
+2. **IBM Plex Sans:** Alternative for a more technical editorial voice.
+3. **IBM Plex Mono:** Recommended for asset IDs, IP addresses, serial numbers,
+ logs, and other machine-oriented data.
+
+Use system sans-serif fallbacks when these fonts are unavailable. Favor medium
+or semibold weights for headings and regular weight for body copy. Avoid
+condensed, decorative, or rounded display type.
+
+## Spacing
+
+Use a 4 px base spacing unit for digital products. Preferred increments are
+4, 8, 12, 16, 24, 32, 48, and 64 px. Align logo placement, typography, and
+supporting elements to a consistent grid.
+
+Brand compositions should have enough open space to feel calm and technical.
+Avoid crowding the mark with borders, controls, or dense copy.
+
+## Icon Usage
+
+Use simple outline icons with consistent stroke weight and square optical
+bounds. Icons should describe actions or system states, not serve as
+decoration. Use filled icons sparingly for selected or critical states.
+
+Prefer Miner Navy or Steel Gray for neutral icons, Ops Orange for active
+emphasis, and semantic colors defined by the product design system for status
+and alerts.
+
+Do not force unrelated interface icons into the hexagonal logo enclosure. The
+hexagon-and-M combination is reserved for the MinerOps brand.
+
+## Tagline Usage
+
+Use the primary tagline for formal product positioning and first introductions.
+Use the secondary tagline for compact campaign copy, presentation endings, or
+operator-focused material.
+
+Taglines should appear as supporting copy and should not be locked permanently
+to the logo artwork. Preserve the exact wording and punctuation shown above.
diff --git a/branding/colors.md b/branding/colors.md
new file mode 100644
index 0000000..0483822
--- /dev/null
+++ b/branding/colors.md
@@ -0,0 +1,40 @@
+# MinerOps Color Palette
+
+## Core Colors
+
+| Color | Hex | Intended usage |
+| --- | --- | --- |
+| Miner Navy | `#0F172A` | Primary brand color, headings, navigation, dark surfaces, and the main logo structure |
+| Ops Orange | `#F97316` | Active emphasis, calls to action, selected states, and the M or Ops accent |
+| Steel Gray | `#475569` | Secondary text, neutral icons, borders, metadata, and supporting UI elements |
+| Light Gray | `#E2E8F0` | Dividers, subtle borders, disabled surfaces, and light neutral backgrounds |
+| White | `#FFFFFF` | Content surfaces, reversed text, and logo details on dark backgrounds |
+
+## Usage Principles
+
+- Use Miner Navy as the primary visual anchor.
+- Reserve Ops Orange for meaningful emphasis rather than large background
+ fields.
+- Use Steel Gray for supporting information that should remain readable without
+ competing with primary content.
+- Use Light Gray to organize interfaces with subtle separation.
+- Use White to preserve clarity and contrast on dark or dense surfaces.
+- Do not introduce gradients into core brand artwork.
+- Check text and control combinations for accessible contrast before production
+ use.
+
+## Common Combinations
+
+| Context | Background | Foreground or accent |
+| --- | --- | --- |
+| Standard light surface | White | Miner Navy with Ops Orange emphasis |
+| Subtle light surface | Light Gray | Miner Navy or Steel Gray |
+| Primary dark surface | Miner Navy | White with Ops Orange emphasis |
+| Neutral metadata | White or Light Gray | Steel Gray |
+| Active control | Ops Orange | Miner Navy or White after contrast review |
+
+## Color Proportions
+
+For general brand compositions, use neutral surfaces and Miner Navy for most of
+the visual area. Ops Orange should typically occupy the smallest share and
+signal action, focus, or product identity.
diff --git a/branding/favicon.svg b/branding/favicon.svg
new file mode 100644
index 0000000..f12dd5b
--- /dev/null
+++ b/branding/favicon.svg
@@ -0,0 +1,5 @@
+
diff --git a/branding/logo-dark.svg b/branding/logo-dark.svg
new file mode 100644
index 0000000..6fe84d2
--- /dev/null
+++ b/branding/logo-dark.svg
@@ -0,0 +1,5 @@
+
diff --git a/branding/logo-light.svg b/branding/logo-light.svg
new file mode 100644
index 0000000..92184da
--- /dev/null
+++ b/branding/logo-light.svg
@@ -0,0 +1,5 @@
+
diff --git a/branding/logo.svg b/branding/logo.svg
new file mode 100644
index 0000000..1dcb79d
--- /dev/null
+++ b/branding/logo.svg
@@ -0,0 +1,5 @@
+
diff --git a/branding/wordmark.svg b/branding/wordmark.svg
new file mode 100644
index 0000000..a7b3f4b
--- /dev/null
+++ b/branding/wordmark.svg
@@ -0,0 +1,9 @@
+
+