# super3/llmjob architecture

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

- Interactive diagram: https://gitdiagram.com/super3/llmjob
- Repository: https://github.com/super3/llmjob

## Overview

LLMJob combines a GPU-node coordination server with LLMJob Earn, an Electron miner and local inference app. The main network workflow is: an operator enrolls a node through Earn; OpenAI-compatible clients submit requests to the server, which routes work to available nodes and returns results. Earn also mines Pearl and can host local LLM inference. The graph preserves those distinct capabilities; several node-worker/server interactions are described only indirectly in the supplied excerpts, so those links are marked unverified.

Main entry points: [`server/src/controllers/openaiController.js`](https://github.com/super3/llmjob/blob/main/server/src/controllers/openaiController.js) (OpenAI Gateway), [`earn/src/main/main.js`](https://github.com/super3/llmjob/blob/main/earn/src/main/main.js) (Earn Desktop App), [`server/src/routes.js`](https://github.com/super3/llmjob/blob/main/server/src/routes.js) (API Routes), [`server/src/services/jobService.js`](https://github.com/super3/llmjob/blob/main/server/src/services/jobService.js) (Job Queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server_api["Server API"]
  node_server_routes["API Routes<br/>[routes.js]"]
  node_node_controller["Node Controller<br/>[nodeController.js]"]
  node_openai_controller["OpenAI Gateway"]
  node_job_controller["Job Controller<br/>[jobController.js]"]
end

subgraph group_network["Node Network"]
  node_node_service["Node Registry<br/>[nodeService.js]"]
  node_job_service["Job Queue<br/>[jobService.js]"]
  node_node_worker["Node Job Worker<br/>[jobWorker.js]"]
  node_node_identity["Node Identity<br/>[node.js]"]
end

subgraph group_earn_mining["Earn Mining"]
  node_earn_app["Earn Desktop App<br/>[main.js]"]
  node_earn_cli["Earn CLI<br/>[earn-cli.js]"]
  node_pearl_engine["Pearl Engine<br/>[pearlEngine.js]"]
  node_pearl_miner["Pearl Miner<br/>[pearlMiner.js]"]
  node_pearl_core["Native Pearl Core<br/>[pearl_core.cc]"]
end

subgraph group_earn_llm["Earn Local LLM"]
  node_llm_fleet["LLM Fleet<br/>[llmFleet.js]"]
  node_llm_manager["LLM Process Manager<br/>[llmManager.js]"]
  node_llm_engine["LLM Engine Setup"]
  node_llama_config["LLM Runtime Helpers<br/>[llama.js]"]
end

subgraph group_persistence["Persistence and Usage"]
  node_api_keys["API Key Service<br/>[apiKeyService.js]"]
  node_logs_usage["Logs and Usage<br/>[logService.js]"]
  node_postgres[("Postgres<br/>[db.js]")]
end

node_operator(("Operator"))
node_api_client(("API Client"))
node_openrouter["Hosted Model Provider"]

node_operator -->|"uses"| node_earn_app
node_operator -->|"uses"| node_earn_cli
node_api_client -->|"calls API"| node_server_routes
node_server_routes -->|"routes node requests"| node_node_controller
node_server_routes -->|"routes inference requests"| node_openai_controller
node_server_routes -->|"routes job requests"| node_job_controller
node_node_controller -->|"updates registry"| node_node_service
node_job_controller -->|"submits and claims"| node_job_service
node_openai_controller -->|"dispatches jobs"| node_job_service
node_openai_controller -->|"checks node status"| node_node_service
node_openai_controller -->|"authenticates usage"| node_api_keys
node_openai_controller -->|"records usage"| node_logs_usage
node_openai_controller -->|"forwards hosted requests"| node_openrouter
node_operator -.->|"configures"| node_api_client
node_earn_app -->|"starts mining"| node_pearl_engine
node_pearl_engine -->|"starts and observes"| node_pearl_miner
node_pearl_miner -.->|"runs native mining"| node_pearl_core
node_earn_app -->|"manages local inference"| node_llm_fleet
node_llm_fleet -.->|"supervises processes"| node_llm_manager
node_llm_manager -->|"builds server command"| node_llama_config
node_llm_engine -->|"resolves binary"| node_llama_config
node_earn_app -->|"installs inference engine"| node_llm_engine
node_earn_app -.->|"enrolls machine"| node_node_identity
node_earn_cli -.->|"enrolls machine"| node_node_identity
node_node_worker -.->|"polls and reports jobs"| node_job_service
node_node_worker -->|"identifies node"| node_node_identity
node_api_keys -.->|"reads and writes keys"| node_postgres
node_logs_usage -.->|"persists usage logs"| node_postgres
node_job_service -->|"persists queued work"| node_postgres
node_node_service -->|"persists node state"| node_postgres

click node_server_routes "https://github.com/super3/llmjob/blob/main/server/src/routes.js"
click node_node_controller "https://github.com/super3/llmjob/blob/main/server/src/controllers/nodeController.js"
click node_openai_controller "https://github.com/super3/llmjob/blob/main/server/src/controllers/openaiController.js"
click node_job_controller "https://github.com/super3/llmjob/blob/main/server/src/controllers/jobController.js"
click node_node_service "https://github.com/super3/llmjob/blob/main/server/src/services/nodeService.js"
click node_job_service "https://github.com/super3/llmjob/blob/main/server/src/services/jobService.js"
click node_earn_app "https://github.com/super3/llmjob/blob/main/earn/src/main/main.js"
click node_earn_cli "https://github.com/super3/llmjob/blob/main/earn/src/cli/earn-cli.js"
click node_pearl_engine "https://github.com/super3/llmjob/blob/main/earn/src/main/pearlEngine.js"
click node_pearl_miner "https://github.com/super3/llmjob/blob/main/earn/src/main/pearlMiner.js"
click node_pearl_core "https://github.com/super3/llmjob/blob/main/earn/native/src/pearl_core.cc"
click node_node_worker "https://github.com/super3/llmjob/blob/main/earn/src/main/jobWorker.js"
click node_node_identity "https://github.com/super3/llmjob/blob/main/earn/src/shared/node.js"
click node_llm_fleet "https://github.com/super3/llmjob/blob/main/earn/src/main/llmFleet.js"
click node_llm_manager "https://github.com/super3/llmjob/blob/main/earn/src/main/llmManager.js"
click node_llm_engine "https://github.com/super3/llmjob/blob/main/earn/src/main/llmEngineManager.js"
click node_llama_config "https://github.com/super3/llmjob/blob/main/earn/src/shared/llama.js"
click node_api_keys "https://github.com/super3/llmjob/blob/main/server/src/services/apiKeyService.js"
click node_logs_usage "https://github.com/super3/llmjob/blob/main/server/src/services/logService.js"
click node_postgres "https://github.com/super3/llmjob/blob/main/server/src/db.js"

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_server_routes,node_node_controller,node_openai_controller,node_job_controller,node_api_client toneBlue
class node_node_service,node_job_service,node_node_worker,node_node_identity toneAmber
class node_earn_app,node_earn_cli,node_pearl_engine,node_pearl_miner,node_pearl_core toneMint
class node_llm_fleet,node_llm_manager,node_llm_engine,node_llama_config toneRose
class node_api_keys,node_logs_usage,node_postgres,node_operator,node_openrouter toneIndigo
```

## Components

### Server API

- [API Routes](https://github.com/super3/llmjob/blob/main/server/src/routes.js): `server/src/routes.js`
- [Node Controller](https://github.com/super3/llmjob/blob/main/server/src/controllers/nodeController.js): `server/src/controllers/nodeController.js`
- [OpenAI Gateway](https://github.com/super3/llmjob/blob/main/server/src/controllers/openaiController.js): `server/src/controllers/openaiController.js`
- [Job Controller](https://github.com/super3/llmjob/blob/main/server/src/controllers/jobController.js): `server/src/controllers/jobController.js`

### Node Network

- [Node Registry](https://github.com/super3/llmjob/blob/main/server/src/services/nodeService.js): `server/src/services/nodeService.js`
- [Job Queue](https://github.com/super3/llmjob/blob/main/server/src/services/jobService.js): `server/src/services/jobService.js`
- [Node Job Worker](https://github.com/super3/llmjob/blob/main/earn/src/main/jobWorker.js): `earn/src/main/jobWorker.js`
- [Node Identity](https://github.com/super3/llmjob/blob/main/earn/src/shared/node.js): `earn/src/shared/node.js`

### Earn Mining

- [Earn Desktop App](https://github.com/super3/llmjob/blob/main/earn/src/main/main.js): `earn/src/main/main.js`
- [Earn CLI](https://github.com/super3/llmjob/blob/main/earn/src/cli/earn-cli.js): `earn/src/cli/earn-cli.js`
- [Pearl Engine](https://github.com/super3/llmjob/blob/main/earn/src/main/pearlEngine.js): `earn/src/main/pearlEngine.js`
- [Pearl Miner](https://github.com/super3/llmjob/blob/main/earn/src/main/pearlMiner.js): `earn/src/main/pearlMiner.js`
- [Native Pearl Core](https://github.com/super3/llmjob/blob/main/earn/native/src/pearl_core.cc): `earn/native/src/pearl_core.cc`

### Earn Local LLM

- [LLM Fleet](https://github.com/super3/llmjob/blob/main/earn/src/main/llmFleet.js): `earn/src/main/llmFleet.js`
- [LLM Process Manager](https://github.com/super3/llmjob/blob/main/earn/src/main/llmManager.js): `earn/src/main/llmManager.js`
- [LLM Engine Setup](https://github.com/super3/llmjob/blob/main/earn/src/main/llmEngineManager.js): `earn/src/main/llmEngineManager.js`
- [LLM Runtime Helpers](https://github.com/super3/llmjob/blob/main/earn/src/shared/llama.js): `earn/src/shared/llama.js`

### Persistence and Usage

- [API Key Service](https://github.com/super3/llmjob/blob/main/server/src/services/apiKeyService.js): `server/src/services/apiKeyService.js`
- [Logs and Usage](https://github.com/super3/llmjob/blob/main/server/src/services/logService.js): `server/src/services/logService.js`
- [Postgres](https://github.com/super3/llmjob/blob/main/server/src/db.js): `server/src/db.js`

### Other components

- **Operator**
- **API Client**
- **Hosted Model Provider**

## Connections

- Operator → Earn Desktop App: uses (evidence: `README.md`)
- Operator → Earn CLI: uses (evidence: `README.md`)
- API Client → API Routes: calls API (evidence: `README.md`)
- API Routes → Node Controller: routes node requests (evidence: `server/src/routes.js`)
- API Routes → OpenAI Gateway: routes inference requests (evidence: `server/src/routes.js`)
- API Routes → Job Controller: routes job requests (evidence: `server/src/routes.js`)
- Node Controller → Node Registry: updates registry (evidence: `server/src/controllers/nodeController.js`)
- Job Controller → Job Queue: submits and claims (evidence: `server/src/controllers/jobController.js`)
- OpenAI Gateway → Job Queue: dispatches jobs (evidence: `server/src/controllers/openaiController.js`)
- OpenAI Gateway → Node Registry: checks node status (evidence: `server/src/controllers/openaiController.js`)
- OpenAI Gateway → API Key Service: authenticates usage (evidence: `server/src/controllers/openaiController.js`)
- OpenAI Gateway → Logs and Usage: records usage (evidence: `server/src/controllers/openaiController.js`)
- OpenAI Gateway → Hosted Model Provider: forwards hosted requests (evidence: `server/src/controllers/openaiController.js`)
- Operator → API Client: configures (evidence: `README.md`)
- Earn Desktop App → Pearl Engine: starts mining (evidence: `earn/src/main/main.js`)
- Pearl Engine → Pearl Miner: starts and observes (evidence: `earn/src/main/pearlEngine.js`)
- Pearl Miner → Native Pearl Core: runs native mining
- Earn Desktop App → LLM Fleet: manages local inference (evidence: `earn/src/main/main.js`)
- LLM Fleet → LLM Process Manager: supervises processes
- LLM Process Manager → LLM Runtime Helpers: builds server command (evidence: `earn/src/main/llmManager.js`)
- LLM Engine Setup → LLM Runtime Helpers: resolves binary (evidence: `earn/src/main/llmEngineManager.js`)
- Earn Desktop App → LLM Engine Setup: installs inference engine (evidence: `earn/src/main/main.js`)
- Earn Desktop App → Node Identity: enrolls machine (evidence: `README.md`)
- Earn CLI → Node Identity: enrolls machine (evidence: `README.md`)
- Node Job Worker → Job Queue: polls and reports jobs
- Node Job Worker → Node Identity: identifies node (evidence: `earn/src/main/jobWorker.js`)
- API Key Service → Postgres: reads and writes keys
- Logs and Usage → Postgres: persists usage logs
- Job Queue → Postgres: persists queued work (evidence: `server/src/services/jobService.js`)
- Node Registry → Postgres: persists node state (evidence: `server/src/services/nodeService.js`)
