Snider/Mining
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #10 from Snider/add-docs-folder

Browse source 
Add descriptive markdown documentation to docs folder
This commit is contained in:
Snider 2025-11-25 00:09:27 +00:00 • committed by GitHub
commit fa618b41a2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 333 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
docs/API.md Normal file
View file

@ -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://<host>:<port>/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.

64
docs/ARCHITECTURE.md Normal file
View file

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

101
docs/CLI.md Normal file
View file

@ -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]
```

90
docs/DEVELOPMENT.md Normal file
View file

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

14
docs/README.md Normal file
View file

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