# shivaa-rana/buildqueue architecture

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

- Interactive diagram: https://gitdiagram.com/shivaa-rana/buildqueue
- Repository: https://github.com/shivaa-rana/buildqueue

## Overview

BuildQueue combines two products: BuildQueue Live runs real file-checksum batches through a desktop UI, while the original application provides a deterministic scheduling and resource simulation through CLI and HTTP/dashboard interfaces. The simulation coordinator owns dispatch and resource admission; the Live batch queue owns real checksum-job scheduling. Edges are limited to excerpted relationships and README statements; the browser-to-server link is marked unverified because its wiring was not shown.

Main entry points: [`src/BuildQueueEngine.cpp`](https://github.com/shivaa-rana/buildqueue/blob/main/src/BuildQueueEngine.cpp) (Tick coordinator), [`web/js/app.js`](https://github.com/shivaa-rana/buildqueue/blob/main/web/js/app.js) (Dashboard), [`live/src/BatchQueue.cpp`](https://github.com/shivaa-rana/buildqueue/blob/main/live/src/BatchQueue.cpp) (Batch queue), [`live/desktop/main.cpp`](https://github.com/shivaa-rana/buildqueue/blob/main/live/desktop/main.cpp) (Qt desktop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["BuildQueue Live"]
  node_desktop["Qt desktop<br/>[main.cpp]"]
  node_batch["Batch queue<br/>[BatchQueue.cpp]"]
  node_checksum["Checksum worker<br/>[Checksum.cpp]"]
  node_pool["Buffer pool<br/>[BufferPool.hpp]"]
  node_deadlock["Deadlock detector"]
  node_liveweb["Live web client<br/>[app.js]"]
end

subgraph group_engine["Simulation engine"]
  node_engine["Tick coordinator"]
  node_jobs["Job state<br/>[JobManager.cpp]"]
  node_scheduler["Policy scheduler"]
  node_memory["Memory allocator<br/>[MemoryManager.cpp]"]
  node_admission["Slot admission<br/>[SyncController.cpp]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[CLI.cpp]"]
  node_http["HTTP server<br/>[HttpServer.cpp]"]
  node_web["Dashboard<br/>[app.js]"]
  node_api["Browser API client<br/>[api.js]"]
  node_charts["Charts and views<br/>[charts.js]"]
  node_components["UI components<br/>[components.js]"]
  node_exports["Data exports<br/>[exports.js]"]
end

subgraph group_runtime["Runtime services"]
  node_workers["Worker pool<br/>[WorkerManager.cpp]"]
  node_metrics["Metrics"]
  node_logger["Execution log<br/>[Logger.cpp]"]
end

node_user(("Operator"))

node_user -->|"submits files"| node_desktop
node_desktop -->|"controls batches"| node_batch
node_batch -->|"runs checksums"| node_checksum
node_checksum -->|"streams through"| node_pool
node_batch -->|"checks deadlocks"| node_deadlock
node_user -->|"submits files"| node_liveweb
node_engine -->|"manages jobs"| node_jobs
node_engine -->|"orders dispatch"| node_scheduler
node_engine -->|"allocates memory"| node_memory
node_engine -->|"acquires slots"| node_admission
node_engine -->|"submits work"| node_workers
node_engine -->|"computes metrics"| node_metrics
node_engine -->|"records events"| node_logger
node_user -->|"issues commands"| node_cli
node_user -->|"uses dashboard"| node_web
node_cli -->|"controls runs"| node_engine
node_http -->|"serves operations"| node_engine
node_web -->|"requests data"| node_api
node_api -.->|"calls endpoints"| node_http
node_web -->|"renders charts"| node_charts
node_web -->|"renders controls"| node_components
node_web -->|"exports comparisons"| node_exports

click node_desktop "https://github.com/shivaa-rana/buildqueue/blob/main/live/desktop/main.cpp"
click node_batch "https://github.com/shivaa-rana/buildqueue/blob/main/live/src/BatchQueue.cpp"
click node_checksum "https://github.com/shivaa-rana/buildqueue/blob/main/live/src/Checksum.cpp"
click node_pool "https://github.com/shivaa-rana/buildqueue/blob/main/live/include/BufferPool.hpp"
click node_deadlock "https://github.com/shivaa-rana/buildqueue/blob/main/live/src/DeadlockDetector.cpp"
click node_liveweb "https://github.com/shivaa-rana/buildqueue/blob/main/live/web/js/app.js"
click node_engine "https://github.com/shivaa-rana/buildqueue/blob/main/src/BuildQueueEngine.cpp"
click node_jobs "https://github.com/shivaa-rana/buildqueue/blob/main/src/JobManager.cpp"
click node_scheduler "https://github.com/shivaa-rana/buildqueue/blob/main/src/SchedulerEngine.cpp"
click node_memory "https://github.com/shivaa-rana/buildqueue/blob/main/src/MemoryManager.cpp"
click node_admission "https://github.com/shivaa-rana/buildqueue/blob/main/src/SyncController.cpp"
click node_workers "https://github.com/shivaa-rana/buildqueue/blob/main/src/WorkerManager.cpp"
click node_metrics "https://github.com/shivaa-rana/buildqueue/blob/main/src/MonitoringEngine.cpp"
click node_logger "https://github.com/shivaa-rana/buildqueue/blob/main/src/Logger.cpp"
click node_cli "https://github.com/shivaa-rana/buildqueue/blob/main/src/CLI.cpp"
click node_http "https://github.com/shivaa-rana/buildqueue/blob/main/src/HttpServer.cpp"
click node_web "https://github.com/shivaa-rana/buildqueue/blob/main/web/js/app.js"
click node_api "https://github.com/shivaa-rana/buildqueue/blob/main/web/js/api.js"
click node_charts "https://github.com/shivaa-rana/buildqueue/blob/main/web/js/charts.js"
click node_components "https://github.com/shivaa-rana/buildqueue/blob/main/web/js/components.js"
click node_exports "https://github.com/shivaa-rana/buildqueue/blob/main/web/js/exports.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_desktop,node_batch,node_checksum,node_pool,node_deadlock,node_liveweb toneBlue
class node_engine,node_jobs,node_scheduler,node_memory,node_admission toneAmber
class node_cli,node_http,node_web,node_api,node_charts,node_components,node_exports toneMint
class node_workers,node_metrics,node_logger toneRose
class node_user toneIndigo
```

## Components

### BuildQueue Live

- [Qt desktop](https://github.com/shivaa-rana/buildqueue/blob/main/live/desktop/main.cpp): `live/desktop/main.cpp`
- [Batch queue](https://github.com/shivaa-rana/buildqueue/blob/main/live/src/BatchQueue.cpp): `live/src/BatchQueue.cpp`
- [Checksum worker](https://github.com/shivaa-rana/buildqueue/blob/main/live/src/Checksum.cpp): `live/src/Checksum.cpp`
- [Buffer pool](https://github.com/shivaa-rana/buildqueue/blob/main/live/include/BufferPool.hpp): `live/include/BufferPool.hpp`
- [Deadlock detector](https://github.com/shivaa-rana/buildqueue/blob/main/live/src/DeadlockDetector.cpp): `live/src/DeadlockDetector.cpp`
- [Live web client](https://github.com/shivaa-rana/buildqueue/blob/main/live/web/js/app.js): `live/web/js/app.js`

### Simulation engine

- [Tick coordinator](https://github.com/shivaa-rana/buildqueue/blob/main/src/BuildQueueEngine.cpp): `src/BuildQueueEngine.cpp`
- [Job state](https://github.com/shivaa-rana/buildqueue/blob/main/src/JobManager.cpp): `src/JobManager.cpp`
- [Policy scheduler](https://github.com/shivaa-rana/buildqueue/blob/main/src/SchedulerEngine.cpp): `src/SchedulerEngine.cpp`
- [Memory allocator](https://github.com/shivaa-rana/buildqueue/blob/main/src/MemoryManager.cpp): `src/MemoryManager.cpp`
- [Slot admission](https://github.com/shivaa-rana/buildqueue/blob/main/src/SyncController.cpp): `src/SyncController.cpp`

### User interfaces

- [CLI](https://github.com/shivaa-rana/buildqueue/blob/main/src/CLI.cpp): `src/CLI.cpp`
- [HTTP server](https://github.com/shivaa-rana/buildqueue/blob/main/src/HttpServer.cpp): `src/HttpServer.cpp`
- [Dashboard](https://github.com/shivaa-rana/buildqueue/blob/main/web/js/app.js): `web/js/app.js`
- [Browser API client](https://github.com/shivaa-rana/buildqueue/blob/main/web/js/api.js): `web/js/api.js`
- [Charts and views](https://github.com/shivaa-rana/buildqueue/blob/main/web/js/charts.js): `web/js/charts.js`
- [UI components](https://github.com/shivaa-rana/buildqueue/blob/main/web/js/components.js): `web/js/components.js`
- [Data exports](https://github.com/shivaa-rana/buildqueue/blob/main/web/js/exports.js): `web/js/exports.js`

### Runtime services

- [Worker pool](https://github.com/shivaa-rana/buildqueue/blob/main/src/WorkerManager.cpp): `src/WorkerManager.cpp`
- [Metrics](https://github.com/shivaa-rana/buildqueue/blob/main/src/MonitoringEngine.cpp): `src/MonitoringEngine.cpp`
- [Execution log](https://github.com/shivaa-rana/buildqueue/blob/main/src/Logger.cpp): `src/Logger.cpp`

### Other components

- **Operator**

## Connections

- Operator → Qt desktop: submits files (evidence: `README.md`)
- Qt desktop → Batch queue: controls batches (evidence: `live/desktop/main.cpp`)
- Batch queue → Checksum worker: runs checksums
- Checksum worker → Buffer pool: streams through
- Batch queue → Deadlock detector: checks deadlocks
- Operator → Live web client: submits files (evidence: `README.md`)
- Tick coordinator → Job state: manages jobs
- Tick coordinator → Policy scheduler: orders dispatch
- Tick coordinator → Memory allocator: allocates memory (evidence: `src/BuildQueueEngine.cpp`)
- Tick coordinator → Slot admission: acquires slots (evidence: `src/BuildQueueEngine.cpp`)
- Tick coordinator → Worker pool: submits work (evidence: `src/BuildQueueEngine.cpp`)
- Tick coordinator → Metrics: computes metrics
- Tick coordinator → Execution log: records events
- Operator → CLI: issues commands (evidence: `README.md`)
- Operator → Dashboard: uses dashboard (evidence: `README.md`)
- CLI → Tick coordinator: controls runs
- HTTP server → Tick coordinator: serves operations
- Dashboard → Browser API client: requests data (evidence: `web/js/app.js`)
- Browser API client → HTTP server: calls endpoints
- Dashboard → Charts and views: renders charts (evidence: `web/js/app.js`)
- Dashboard → UI components: renders controls (evidence: `web/js/app.js`)
- Dashboard → Data exports: exports comparisons (evidence: `web/js/app.js`)
