# nirmitaggarwal/volunteer_cloud architecture

> Architecture diagram of the GitHub repository nirmitaggarwal/volunteer_cloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nirmitaggarwal/volunteer_cloud
- Repository: https://github.com/nirmitaggarwal/volunteer_cloud

## Overview

Volunteer Cloud coordinates volunteer machines to benchmark/register, receive benchmark-matched tasks, verify and execute signed plugins, report progress/results, and recover work after worker failures. Python Flask and Rust/Actix are parallel control-server implementations. The graph preserves the plugin, monitoring, fault-recovery, and persistence capabilities documented in the README; several Rust internals and dashboard templates were not sampled, so their implementation-level links are limited.

Main entry points: [`worker/worker.py`](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/worker/worker.py) (Worker agent), [`control_server/server.py`](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/control_server/server.py) (Flask orchestrator), [`control_server_rust/src/main.rs`](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/control_server_rust/src/main.rs) (Rust orchestrator), [`plugins`](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/plugins) (Workload plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Volunteer clients"]
  node_worker["Worker agent<br/>[worker.py]"]
  node_worker_cache[("Plugin cache")]
  node_job_runs["Job outputs"]
end

subgraph group_orchestration["Control servers"]
  node_python_server["Flask orchestrator<br/>[server.py]"]
  node_rust_server["Rust orchestrator<br/>[main.rs]"]
end

subgraph group_workloads["Plugins and verification"]
  node_plugins["Workload plugins"]
  node_plugin_security["Plugin verification<br/>[worker.py]"]
end

subgraph group_operations["Monitoring and records"]
  node_python_store[("Python CSV records")]
  node_rust_store[("Rust CSV records")]
  node_python_dashboard["Python dashboard"]
  node_rust_dashboard["Rust dashboard"]
end

node_volunteer(("Volunteer operator"))
node_admin(("Dashboard viewer"))

node_volunteer -->|"starts worker"| node_worker
node_worker -->|"registers and polls"| node_python_server
node_worker -->|"registers and polls"| node_rust_server
node_worker -->|"sends heartbeat"| node_python_server
node_worker -->|"sends heartbeat"| node_rust_server
node_python_server -->|"assigns tasks"| node_worker
node_rust_server -->|"assigns tasks"| node_worker
node_worker -->|"verifies bundle"| node_plugin_security
node_plugin_security -->|"reads and caches"| node_worker_cache
node_python_server -->|"serves signed bundles"| node_plugins
node_worker -->|"downloads and executes"| node_plugins
node_worker -->|"writes output"| node_job_runs
node_worker -->|"reports progress and results"| node_python_server
node_worker -->|"reports progress and results"| node_rust_server
node_python_server -->|"persists records"| node_python_store
node_rust_server -->|"persists records"| node_rust_store
node_python_server -->|"renders monitoring views"| node_python_dashboard
node_rust_server -->|"routes dashboard views"| node_rust_dashboard
node_admin -->|"views status"| node_python_dashboard
node_admin -->|"views status"| node_rust_dashboard
node_python_server -->|"requeues failed work"| node_python_server
node_rust_server -->|"requeues failed work"| node_rust_server

click node_worker "https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/worker/worker.py"
click node_worker_cache "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/worker/plugin_cache"
click node_job_runs "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/worker/job_runs"
click node_python_server "https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/control_server/server.py"
click node_rust_server "https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/control_server_rust/src/main.rs"
click node_plugins "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/plugins"
click node_plugin_security "https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/worker/worker.py"
click node_python_store "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server/storage"
click node_rust_store "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server_rust/storage"
click node_python_dashboard "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server/templates"
click node_rust_dashboard "https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server_rust/templates"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_worker,node_worker_cache,node_job_runs,node_admin toneBlue
class node_python_server,node_rust_server toneAmber
class node_plugins,node_plugin_security toneMint
class node_python_store,node_rust_store,node_python_dashboard,node_rust_dashboard toneRose
class node_volunteer toneIndigo
```

## Components

### Volunteer clients

- [Worker agent](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/worker/worker.py): `worker/worker.py`
- [Plugin cache](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/worker/plugin_cache): `worker/plugin_cache`
- [Job outputs](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/worker/job_runs): `worker/job_runs`

### Control servers

- [Flask orchestrator](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/control_server/server.py): `control_server/server.py`
- [Rust orchestrator](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/control_server_rust/src/main.rs): `control_server_rust/src/main.rs`

### Plugins and verification

- [Workload plugins](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/plugins): `plugins`
- [Plugin verification](https://github.com/nirmitaggarwal/volunteer_cloud/blob/main/worker/worker.py): `worker/worker.py`

### Monitoring and records

- [Python CSV records](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server/storage): `control_server/storage`
- [Rust CSV records](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server_rust/storage): `control_server_rust/storage`
- [Python dashboard](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server/templates): `control_server/templates`
- [Rust dashboard](https://github.com/nirmitaggarwal/volunteer_cloud/tree/main/control_server_rust/templates): `control_server_rust/templates`

### Other components

- **Volunteer operator**
- **Dashboard viewer**

## Connections

- Volunteer operator → Worker agent: starts worker (evidence: `README.md`)
- Worker agent → Flask orchestrator: registers and polls (evidence: `README.md`)
- Worker agent → Rust orchestrator: registers and polls (evidence: `README.md`)
- Worker agent → Flask orchestrator: sends heartbeat (evidence: `worker/worker.py`)
- Worker agent → Rust orchestrator: sends heartbeat (evidence: `worker/worker.py`)
- Flask orchestrator → Worker agent: assigns tasks (evidence: `README.md`)
- Rust orchestrator → Worker agent: assigns tasks (evidence: `README.md`)
- Worker agent → Plugin verification: verifies bundle (evidence: `worker/worker.py`)
- Plugin verification → Plugin cache: reads and caches (evidence: `worker/worker.py`)
- Flask orchestrator → Workload plugins: serves signed bundles (evidence: `control_server/server.py`)
- Worker agent → Workload plugins: downloads and executes (evidence: `README.md`)
- Worker agent → Job outputs: writes output (evidence: `worker/worker.py`)
- Worker agent → Flask orchestrator: reports progress and results (evidence: `worker/worker.py`)
- Worker agent → Rust orchestrator: reports progress and results (evidence: `README.md`)
- Flask orchestrator → Python CSV records: persists records (evidence: `control_server/server.py`)
- Rust orchestrator → Rust CSV records: persists records (evidence: `control_server_rust/src/main.rs`)
- Flask orchestrator → Python dashboard: renders monitoring views (evidence: `README.md`)
- Rust orchestrator → Rust dashboard: routes dashboard views (evidence: `control_server_rust/src/main.rs`)
- Dashboard viewer → Python dashboard: views status (evidence: `README.md`)
- Dashboard viewer → Rust dashboard: views status (evidence: `README.md`)
- Flask orchestrator → Flask orchestrator: requeues failed work (evidence: `README.md`)
- Rust orchestrator → Rust orchestrator: requeues failed work (evidence: `README.md`)