> For the complete documentation index, see [llms.txt](https://docs.hashcloud.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hashcloud.sh/architecture-overview/hashcloud-system-architecture.md).

# HashCloud System Architecture

### Overview

This document explains the high-level architecture of the HashCloud mining platform, including the Staking Contract, Backend Server, and Miner CLI interactions.

***

### 🧩 System Components

#### **1. Staking Contract (On-Chain Smart Contract)**

* Controls **14-day reward cycle**.
* Issues a new **poolId** at the start of each cycle.
* Stores **user tiers** (VIP0 to VIP4).
* Provides **multiplier values** based on user tier.
* Source of truth for:
  * `activePoolId`
  * `user tier`

**Used by:** Backend server and Miner CLI to read current `activePoolId` and tier multipliers.

***

#### **2. Backend Server**

* Subscribes to events from the staking contract.
* Caches current `activePoolId`.
* Maps **user tier → reward multiplier**.
* Receives and stores **miner submissions (scores)**.
* After each cycle ends:
  * Calculates final rewards.
  * Signs reward claim data for miners.

**API Endpoints Example:**

* `GET /api/pool/active` → Returns current active `poolId`.
* `POST /api/submit` → Miner submissions with scores and wallet address.

***

#### **3. Miner CLI (Mining Client Application)**

* Fetches the current `activePoolId` from Backend.
* Begins mining **only when a pool is active**.
* Tags every submission with the `poolId`.
* Sends mined scores to Backend for reward calculation.

***

### 🔄 Workflow Summary

1. **Staking Contract** starts a 14-day cycle and sets `activePoolId`.
2. **Backend Server** listens, stores `poolId`, and prepares multiplier logic.
3. **Miner CLI** requests `activePoolId` and starts mining.
4. Miners submit scores → Backend collects and logs them.
5. At cycle end, Backend calculates rewards and signs claim data.

***

### ✅ Benefits of This Architecture

* **Fair Reward Distribution** via tier system and multipliers.
* **Decentralized Trust** (pool data is from on-chain contract).
* **Scalable** — miners only depend on minimal API endpoints.
* **Secure** — reward claims require server-side cryptographic signature.

***

### 📌 Next Steps

* Add diagrams to GitBook.
* Document exact API request/response payloads.
* Provide sample Miner CLI configuration.

***

Would you like me to add diagrams, API specs, or format this into Markdown for GitBook directly?

### 📊 System Diagram 

```
graph TD;
A[Staking Contract] -->|activePoolId + user tier| B[Backend Server];
B -->|API: /api/pool/active, /api/submit| C[Miner CLI];


subgraph A1[Staking Contract]
A1A[Controls 14-day cycle]
A1B[Issues new poolId each cycle]
A1C[Stores user tier]
end


subgraph B1[Backend Server]
B1A[Listens to contract events]
B1B[Caches current poolId]
B1C[Maps tier to multiplier]
B1D[Receives miner submissions]
B1E[Signs reward claims per cycle]
end


subgraph C1[Miner CLI]
C1A[Fetches active poolId]
C1B[Starts mining only when active]
C1C[Tags submissions with poolId]
C1D[Sends scores to backend]
end
```