Mining/docs/development/architecture.md

# Architecture

This document provides a detailed overview of the Mining Platform architecture, design decisions, and component interactions.

## High-Level Architecture

The Mining Platform follows a modular, layered architecture:

```
┌─────────────────────────────────────────────────────────┐
│                    User Interfaces                       │
│  ┌──────────┐  ┌───────────────┐  ┌─────────────────┐  │
│  │   CLI    │  │ Web Dashboard │  │ Desktop App     │  │
│  │  (Cobra) │  │   (Angular)   │  │  (Wails+Angular)│  │
│  └────┬─────┘  └───────┬───────┘  └────────┬────────┘  │
└───────┼────────────────┼───────────────────┼───────────┘
        │                │                   │
        └────────────────┼───────────────────┘
                         │
┌────────────────────────┼───────────────────────────────┐
│                 REST API Layer (Gin)                    │
│                  /api/v1/mining/*                       │
└────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────┼───────────────────────────────┐
│              Core Business Logic (pkg/mining)           │
│  ┌──────────────┐  ┌─────────────┐  ┌───────────────┐ │
│  │   Manager    │  │   Miner     │  │   Profile     │ │
│  │  Interface   │  │ Implemen-   │  │   Manager     │ │
│  │              │  │   tations   │  │               │ │
│  └──────┬───────┘  └──────┬──────┘  └───────┬───────┘ │
└─────────┼──────────────────┼─────────────────┼─────────┘
          │                  │                 │
┌─────────┼──────────────────┼─────────────────┼─────────┐
│    System Layer (OS, Filesystem, Processes)             │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Mining Software (XMRig, T-Rex, lolMiner, etc.)  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

## Core Components

### Manager Interface

The `ManagerInterface` is the central abstraction for miner lifecycle management.

**Location:** `pkg/mining/manager.go`

**Purpose:**
- Provides a contract for miner operations
- Enables testing through mocking
- Supports multiple miner implementations
- Manages running miners in-memory

**Interface Definition:**

```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()
}
```

**Implementation Details:**
- Maintains a `map[string]Miner` for running miners
- Automatically collects statistics every 10 seconds
- Supports autostart from configuration
- Thread-safe with mutex locks

### Miner Interface

The `Miner` interface defines the contract for all miner implementations.

**Location:** `pkg/mining/mining.go`

**Interface Definition:**

```go
type Miner interface {
    GetName() string
    GetStats() (*PerformanceMetrics, error)
    Stop() error
    IsRunning() bool
    GetConfig() *Config
    GetHashrateHistory() []HashratePoint
}
```

**Implementations:**
- **XMRigMiner**: CPU/GPU mining for RandomX and CryptoNight
- **TRexMiner**: NVIDIA GPU mining for KawPow, Ethash (future)
- **LolMiner**: AMD/NVIDIA mining for Ethash, Beam (future)

### BaseMiner

Provides shared functionality for all miner implementations.

**Location:** `pkg/mining/miner.go`

**Features:**
- Binary discovery and installation
- Archive extraction (tar.gz, tar.xz, zip)
- Download from URLs with progress tracking
- Hashrate history management
- XDG directory compliance

**Key Methods:**

```go
func (m *BaseMiner) InstallFromURL(url string) error
func (m *BaseMiner) FindBinary(name string) (string, error)
func (m *BaseMiner) AddHashratePoint(hashrate float64)
func (m *BaseMiner) GetHashrateHistory() []HashratePoint
```

**Hashrate History:**
- High-resolution: 10-second intervals, 5-minute retention
- Low-resolution: 1-minute averages, 24-hour retention
- Automatically manages data retention

### XMRig Implementation

Complete implementation for XMRig miner.

**Files:**
- `pkg/mining/xmrig.go`: Core implementation
- `pkg/mining/xmrig_start.go`: Startup logic
- `pkg/mining/xmrig_stats.go`: Statistics parsing

**Architecture:**

```
┌─────────────────────────────────────────────┐
│           XMRigMiner                        │
│  ┌─────────────────────────────────────┐   │
│  │        BaseMiner (embedded)         │   │
│  │  - Binary management                │   │
│  │  - Hashrate history                 │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  Start() → Generate config.json            │
│         → Execute xmrig binary             │
│         → Capture stdout/stderr            │
│         → Monitor process                  │
│                                             │
│  GetStats() → Poll HTTP API                │
│            → Parse JSON response           │
│            → Return PerformanceMetrics     │
│                                             │
│  Stop() → Send SIGTERM                     │
│        → Wait for graceful shutdown        │
│        → Force kill if needed              │
└─────────────────────────────────────────────┘
```

**Configuration Generation:**
- Creates JSON config file
- Supports CPU and GPU mining
- Handles pool authentication
- Manages algorithm selection
- Configures API endpoint for stats

**Statistics Collection:**
- Polls XMRig HTTP API (default: `http://127.0.0.1:44321/1/summary`)
- Parses JSON response
- Extracts hashrate, shares, connection info
- Updates hashrate history

### Service Layer (REST API)

Exposes the Manager functionality via HTTP endpoints.

**Location:** `pkg/mining/service.go`

**Framework:** Gin Web Framework

**Features:**
- RESTful API design
- Swagger documentation
- CORS support
- JSON request/response
- Error handling middleware
- Route grouping

**Route Organization:**

```
/api/v1/mining
├── /info                    # GET - System info
├── /doctor                  # POST - Diagnostics
├── /update                  # POST - Check updates
├── /miners
│   ├── /                    # GET - List miners
│   ├── /available           # GET - Available types
│   ├── /:miner_type         # POST - Start miner
│   ├── /:miner_name         # DELETE - Stop miner
│   ├── /:miner_name/stats   # GET - Get statistics
│   ├── /:miner_type/install # POST - Install miner
│   └── /:miner_type/uninstall # DELETE - Uninstall
└── /profiles
    ├── /                    # GET - List profiles
    ├── /                    # POST - Create profile
    ├── /:id                 # GET - Get profile
    ├── /:id                 # PUT - Update profile
    ├── /:id                 # DELETE - Delete profile
    └── /:id/start           # POST - Start from profile
```

**Middleware Stack:**
1. Logger
2. Recovery (panic handler)
3. CORS
4. Request validation
5. Response formatter

### Profile Manager

Manages saved mining configurations.

**Location:** `pkg/mining/profile_manager.go`

**Storage:** JSON file at `~/.config/lethean-desktop/mining_profiles.json`

**Data Structure:**

```go
type MiningProfile struct {
    ID          string    `json:"id"`
    Name        string    `json:"name"`
    Description string    `json:"description,omitempty"`
    MinerType   string    `json:"minerType"`
    Config      *Config   `json:"config"`
    CreatedAt   time.Time `json:"createdAt"`
    UpdatedAt   time.Time `json:"updatedAt"`
}
```

**Features:**
- CRUD operations for profiles
- UUID-based profile IDs
- Atomic file writes
- Import/export support
- Validation

### Config Manager

Handles autostart and last-used configurations.

**Location:** `pkg/mining/config_manager.go`

**Storage:** JSON file at `~/.config/lethean-desktop/mining_config.json`

**Features:**
- Autostart configuration
- Last-used miner configs
- Preference storage
- Default settings

## Data Flow

### Starting a Miner

```
User Request
    │
    ├─→ CLI: miner-ctrl start xmrig --config config.json
    ├─→ API: POST /api/v1/mining/miners/xmrig
    └─→ Desktop: profileManager.start(profileId)
    │
    ▼
Service Layer (service.go)
    │
    ├─→ Validate request
    ├─→ Parse configuration
    └─→ Call manager.StartMiner()
    │
    ▼
Manager (manager.go)
    │
    ├─→ Check if miner already running
    ├─→ Validate configuration
    └─→ Create miner instance
    │
    ▼
Miner Implementation (xmrig.go)
    │
    ├─→ Generate config.json
    ├─→ Find/verify binary
    ├─→ Execute miner process
    ├─→ Capture output streams
    └─→ Start statistics collection
    │
    ▼
Manager
    │
    ├─→ Store miner in running map
    └─→ Return miner instance
    │
    ▼
Service Layer
    │
    ├─→ Format response
    └─→ Return HTTP 200/201
```

### Collecting Statistics

```
Background goroutine (every 10s)
    │
    ▼
For each running miner:
    │
    ├─→ miner.GetStats()
    │       │
    │       ├─→ Poll HTTP API
    │       ├─→ Parse JSON
    │       └─→ Return PerformanceMetrics
    │
    ├─→ Extract hashrate
    └─→ miner.AddHashratePoint(hashrate)
            │
            ├─→ Store in high-res buffer
            ├─→ Update low-res averages
            └─→ Prune old data
```

### Retrieving Statistics (API Request)

```
Client: GET /api/v1/mining/miners/xmrig/stats
    │
    ▼
Service Layer
    │
    ├─→ Extract miner name
    └─→ Call manager.GetMiner(name)
    │
    ▼
Manager
    │
    ├─→ Lookup in miners map
    └─→ Return miner instance
    │
    ▼
Service Layer
    │
    ├─→ Call miner.GetStats()
    ├─→ Format response
    └─→ Return JSON
```

## Frontend Architecture (Angular)

### Component Hierarchy

```
AppComponent
├── DashboardPage
│   ├── MinerStatusCard
│   ├── HashrateCard
│   ├── SharesCard
│   └── EarningsCard
├── MinersPage
│   ├── RunningMinersList
│   │   └── MinerCard
│   └── AvailableMinersList
│       └── MinerInstallCard
├── ProfilesPage
│   ├── ProfileList
│   │   └── ProfileCard
│   └── ProfileEditor
├── StatisticsPage
│   ├── HashrateChart
│   ├── SharesChart
│   └── TimeRangeSelector
├── PoolsPage
│   ├── RecommendedPools
│   └── CustomPoolForm
├── AdminPage
│   ├── SystemInfo
│   ├── MinerManagement
│   └── DiagnosticsPanel
└── SettingsPage
    ├── GeneralSettings
    ├── NotificationSettings
    └── AdvancedSettings
```

### Services

**MinerService**
- API communication
- Miner lifecycle management
- Statistics fetching

**ProfileService**
- Profile CRUD operations
- Profile storage
- Import/export

**WebSocketService**
- Real-time updates
- Event notifications
- Connection management

**ThemeService**
- Theme switching
- Preference persistence

### State Management

The application uses RxJS for state management:

- Services emit observables
- Components subscribe to updates
- Automatic cleanup on destroy
- Centralized error handling

## Desktop Application (Wails)

### Architecture

```
┌─────────────────────────────────────────┐
│         Go Backend (main.go)            │
│  ┌───────────────────────────────────┐  │
│  │     MiningService                 │  │
│  │  - Wraps pkg/mining.Manager       │  │
│  │  - Exposes methods to frontend    │  │
│  └────────────┬──────────────────────┘  │
└───────────────┼─────────────────────────┘
                │ Wails Bindings
┌───────────────┼─────────────────────────┐
│         TypeScript Frontend             │
│  ┌────────────┴──────────────────────┐  │
│  │   Angular Application             │  │
│  │ (Embedded from ui/dist/browser)   │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

**MiningService** (`miningservice.go`):
- Binds Go methods to frontend
- Handles lifecycle events
- Manages application state
- Provides system tray integration

**Auto-generated Bindings** (`frontend/bindings/`):
- TypeScript definitions
- Type-safe Go method calls
- Event system integration

## Modified XMRig Core

### OpenCL Backend

**Location:** `miner/core/src/backend/opencl/`

**Supported Algorithms:**
- ETChash (Ethereum Classic)
- ProgPowZ (Zano)
- KawPow (Ravencoin)

**Key Files:**
- `cl/etchash/`: OpenCL kernels for ETChash
- `cl/progpowz/`: OpenCL kernels for ProgPowZ
- `runners/OclEtchashRunner.*`: ETChash GPU runner
- `runners/OclProgPowZRunner.*`: ProgPowZ GPU runner

### Algorithm Implementations

**Location:** `miner/core/src/crypto/`

**ETChash:**
- `ETCCache.cpp/h`: DAG cache management
- Ethash variant optimized for ETC

**ProgPowZ:**
- Custom ProgPow variant for Zano
- Period-based algorithm rotation

### Build System

CMake-based build with conditional compilation:

```cmake
option(WITH_OPENCL "Enable OpenCL backend" ON)
option(WITH_CUDA "Enable CUDA backend" ON)
```

Automatically detects:
- OpenCL SDK
- CUDA Toolkit
- GPU capabilities

## Security Considerations

### API Security

- No authentication by default (local use)
- Consider reverse proxy for production
- CORS enabled for web component
- Input validation on all endpoints

### File System

- XDG Base Directory compliance
- Restricted file permissions (0644 for config, 0755 for binaries)
- Atomic file writes for configs
- Safe path handling (no path traversal)

### Process Management

- Graceful shutdown (SIGTERM → SIGKILL)
- Process isolation
- Resource limits (if configured)
- Log rotation

## Performance Optimizations

### Hashrate History

- Two-tier storage (high-res + low-res)
- Automatic data pruning
- In-memory ring buffers
- Minimal memory footprint

### Statistics Collection

- Background goroutine (non-blocking)
- Cached HTTP requests
- JSON parsing optimization
- Error resilience

### Frontend

- Lazy loading of routes
- Virtual scrolling for large lists
- Chart data decimation
- Debounced API calls

## Extensibility

### Adding New Miners

1. Implement `Miner` interface
2. Extend `BaseMiner` for common functionality
3. Register in `Manager`
4. Add API endpoints if needed

### Adding New Algorithms

1. Add algorithm support to miner core
2. Update configuration structs
3. Add validation rules
4. Update UI selectors

### Adding New Frontends

The REST API is frontend-agnostic:
- Mobile apps (React Native, Flutter)
- CLI tools
- Third-party integrations
- Monitoring dashboards

## Deployment Patterns

### Single User (Local)

```
User Machine
├── miner-ctrl (CLI/API server)
├── Browser (accessing localhost:8080)
└── Mining software (XMRig, etc.)
```

### Multi-User (Server)

```
Server
├── miner-ctrl (API server on 0.0.0.0:8080)
└── Mining software

Reverse Proxy (nginx)
├── HTTPS termination
├── Authentication
└── Rate limiting

Clients
├── Web browsers
├── Mobile apps
└── API clients
```

### Desktop (Standalone)

```
Single Binary (Wails)
├── Embedded API server
├── Embedded frontend
└── Integrated mining software
```

## Next Steps

- Review [Development Guide](index.md) for setup instructions
- Read [Contributing Guidelines](contributing.md) for contribution process
- See [API Documentation](../api/index.md) for endpoint details