From 960ae087fac62be08288d7aff4ff0d82c437be1d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 25 Nov 2025 00:03:35 +0000 Subject: [PATCH] Add descriptive markdown documentation to docs folder Added comprehensive documentation including: - API.md: REST API reference. - CLI.md: Command Line Interface usage. - ARCHITECTURE.md: System design and components. - DEVELOPMENT.md: Developer guide. - README.md: Index for the documentation. --- docs/API.md | 64 +++++++++++++++++++++++++++ docs/ARCHITECTURE.md | 64 +++++++++++++++++++++++++++ docs/CLI.md | 101 +++++++++++++++++++++++++++++++++++++++++++ docs/DEVELOPMENT.md | 90 ++++++++++++++++++++++++++++++++++++++ docs/README.md | 14 ++++++ 5 files changed, 333 insertions(+) create mode 100644 docs/API.md create mode 100644 docs/ARCHITECTURE.md create mode 100644 docs/CLI.md create mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/README.md diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..e34ff55 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,64 @@ +# Mining API Documentation + +The Mining project provides a comprehensive RESTful API for managing cryptocurrency miners. This API is served by the `miner-cli serve` command. + +## Swagger Documentation + +The project includes automatically generated Swagger (OpenAPI) documentation. + +When you run the service (e.g., `miner-cli serve`), the Swagger UI is available at: + +``` +http://:/api/v1/mining/swagger/index.html +``` + +(Default: `http://localhost:8080/api/v1/mining/swagger/index.html`) + +You can also find the raw Swagger files in this directory: +- [swagger.json](swagger.json) +- [swagger.yaml](swagger.yaml) + +## API Endpoints Summary + +All endpoints are prefixed with `/api/v1/mining` (or the configured `--namespace`). + +### System & Health + +| Method | Endpoint | Description | +| :--- | :--- | :--- | +| `GET` | `/info` | Retrieves cached installation details for all miners and system info. | +| `POST` | `/doctor` | Performs a live check on all available miners to verify installation status. | +| `POST` | `/update` | Checks if any installed miners have a new version available. | + +### Miner Management + +| Method | Endpoint | Description | +| :--- | :--- | :--- | +| `GET` | `/miners` | List all currently running miners. | +| `GET` | `/miners/available` | List all miner types supported by the system. | +| `POST` | `/miners/:miner_type` | Start a new miner instance. Requires a JSON config body. | +| `DELETE` | `/miners/:miner_name` | Stop a running miner instance. | +| `POST` | `/miners/:miner_type/install` | Install or update a specific miner binary. | +| `DELETE` | `/miners/:miner_type/uninstall` | Uninstall a specific miner and remove its files. | +| `GET` | `/miners/:miner_name/stats` | Get real-time statistics (hashrate, shares, etc.) for a running miner. | +| `GET` | `/miners/:miner_name/hashrate-history` | Get historical hashrate data. | + +## Data Models + +### SystemInfo +Contains OS, Architecture, Go Version, total RAM, and a list of installed miners. + +### Miner Configuration (Config) +A comprehensive object containing settings for the miner, such as: +- `pool`: Mining pool address. +- `wallet`: Wallet address. +- `cpuPriority`: CPU priority settings. +- `threads`: Number of threads to use. +- `algo`: Algorithm to mine. + +### PerformanceMetrics +Real-time stats from the miner: +- `hashrate`: Current hashrate in H/s. +- `shares`: Total shares submitted. +- `rejected`: Rejected shares. +- `uptime`: Time since start in seconds. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..1ad5477 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,64 @@ +# Mining Architecture Guide + +This document provides an overview of the architecture of the Mining project. + +## High-Level Overview + +The project is structured as a modular Go application. It consists of: +1. **Core Library (`pkg/mining`)**: Contains the business logic for miner management. +2. **CLI (`cmd/mining`)**: A command-line interface built with Cobra. +3. **REST API**: A Gin-based web server exposed via the `serve` command. +4. **Frontend**: An Angular-based dashboard for monitoring miners. + +## Core Components + +### Manager Interface +The core of the system is the `ManagerInterface` defined in `pkg/mining/manager_interface.go`. This interface abstracts the operations of starting, stopping, and monitoring miners. + +```go +type ManagerInterface interface { + StartMiner(minerType string, config *Config) (Miner, error) + StopMiner(name string) error + GetMiner(name string) (Miner, error) + ListMiners() []Miner + ListAvailableMiners() []AvailableMiner + GetMinerHashrateHistory(name string) ([]HashratePoint, error) + Stop() +} +``` + +This abstraction allows for: +- Easier testing (mocking the manager). +- Pluggable implementations (e.g., supporting different miner backends). + +### Miner Interface +Each specific miner (e.g., XMRig) implements the `Miner` interface. This interface defines how to interact with the underlying miner executable process, parse its output, and control it. + +The `XMRigMiner` implementation (`pkg/mining/xmrig.go`) handles: +- Downloading and verifying the miner binary. +- Generating configuration files. +- Executing the binary. +- Parsing stdout/stderr/API for stats. + +### Service Layer +The `Service` struct (`pkg/mining/service.go`) wraps the `Manager` and exposes its functionality via a HTTP API using the Gin framework. It handles: +- Route registration. +- Request validation/binding. +- Response formatting. +- Swagger documentation generation. + +## Directory Structure + +- `cmd/mining/`: Entry point for the application. +- `pkg/mining/`: Core library code. +- `docs/`: Documentation and Swagger files. +- `ui/`: Source code for the Angular frontend. +- `dist/`: Build artifacts (binaries). + +## Data Flow + +1. **User Action**: User issues a command via CLI or calls an API endpoint. +2. **Service/CMD Layer**: The request is validated and passed to the `Manager`. +3. **Manager Layer**: The manager looks up the appropriate `Miner` implementation. +4. **Miner Layer**: The miner instance interacts with the OS (filesystem, processes). +5. **Feedback**: Status and stats are returned up the stack to the user. diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 0000000..b8eb722 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,101 @@ +# Mining CLI Documentation + +The `miner-cli` is the command-line interface for the Mining project. It allows you to manage miners directly from the terminal or start a REST API server. + +## Installation + +```bash +go install github.com/Snider/Mining/cmd/mining@latest +``` + +## Global Flags + +- `--config string`: Config file (default is $HOME/.mining.yaml) +- `--help`: Help for the command + +## Commands + +### `serve` +Starts the mining service and interactive shell. + +**Usage:** +```bash +miner-cli serve [flags] +``` + +**Flags:** +- `--host`: Host to listen on (default "0.0.0.0") +- `-p, --port`: Port to listen on (default 8080) +- `-n, --namespace`: API namespace for the swagger UI (default "/") + +### `start` +Start a new miner. + +**Usage:** +```bash +miner-cli start [miner-type] [flags] +``` + +### `stop` +Stop a running miner. + +**Usage:** +```bash +miner-cli stop [miner-name] +``` + +### `status` +Get status of a running miner. + +**Usage:** +```bash +miner-cli status [miner-name] +``` + +### `list` +List running and available miners. + +**Usage:** +```bash +miner-cli list +``` + +### `install` +Install or update a miner. + +**Usage:** +```bash +miner-cli install [miner-type] +``` + +### `uninstall` +Uninstall a miner. + +**Usage:** +```bash +miner-cli uninstall [miner-type] +``` + +### `update` +Check for updates to installed miners. + +**Usage:** +```bash +miner-cli update +``` + +### `doctor` +Check and refresh the status of installed miners. + +**Usage:** +```bash +miner-cli doctor +``` + +### `completion` +Generate the autocompletion script for the specified shell (bash, zsh, fish, powershell). + +**Usage:** +```bash +miner-cli completion [shell] +``` diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..99ecfe1 --- /dev/null +++ b/docs/DEVELOPMENT.md @@ -0,0 +1,90 @@ +# Mining Development Guide + +This guide is for developers contributing to the Mining project. + +## Prerequisites + +- **Go**: Version 1.24 or higher. +- **Make**: For running build scripts. +- **Node.js/npm**: For building the frontend (optional). + +## Common Tasks + +The project uses a `Makefile` to automate common tasks. + +### Building + +Build the CLI binary for the current platform: +```bash +make build +``` + +Build for all supported platforms (cross-compile): +```bash +make build-all +``` + +The binaries will be placed in the `dist/` directory. + +### Testing + +Run all Go tests: +```bash +make test +``` + +Run tests with race detection and coverage: +```bash +make test-release +``` + +Generate and view HTML coverage report: +```bash +make coverage +``` + +### Linting & Formatting + +Format code: +```bash +make fmt +``` + +Run linters (requires `golangci-lint`): +```bash +make lint +``` + +### Documentation + +Generate Swagger documentation from code annotations: +```bash +make docs +``` +(Requires `swag` tool: `make install-swag`) + +### Release + +The project uses GoReleaser for releases. +To create a local snapshot release: +```bash +make package +``` + +## Project Structure + +- **`pkg/mining`**: This is where the core logic resides. If you are adding a new feature, you will likely work here. +- **`cmd/mining`**: If you are adding a new CLI command, look here. +- **`ui`**: Frontend code. + +## Contribution Workflow + +1. Fork the repository. +2. Create a feature branch. +3. Make your changes. +4. Ensure tests pass (`make test`). +5. Submit a Pull Request. + +## CodeRabbit + +This project uses CodeRabbit for automated code reviews. Please address any feedback provided by the bot on your PR. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..51c97be --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Mining Documentation + +Welcome to the documentation for the Mining project. This folder contains detailed information about the API, CLI, architecture, and development processes. + +## Documentation Index + +- [**API Documentation**](API.md): Detailed information about the RESTful API endpoints, request/response formats, and Swagger usage. +- [**CLI Documentation**](CLI.md): A comprehensive guide to the Command Line Interface, including command descriptions and usage examples. +- [**Architecture Guide**](ARCHITECTURE.md): An overview of the project's design, including the modular `ManagerInterface`, core packages, and data flow. +- [**Development Guide**](DEVELOPMENT.md): Instructions for contributors on how to build, test, and release the project. + +## Quick Start + +For a quick start guide, please refer to the main [README.md](../README.md) in the project root.