# hrishikeshchandi/adaptive-rl-task-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/hrishikeshchandi/adaptive-rl-task-orchestrator
- Repository: https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator

## Overview

This is a distributed task orchestrator: clients submit resource-requirement and priority data, the API stores tasks, workers register and pull capacity-fitting tasks, and the scheduler scores candidates using duration estimates and Q-learning weights. Workers report outcomes, which feed task history and the background learner’s Q-table updates. Recovery and heartbeat services provide retries and dead-worker handling; the README also documents Prometheus/Grafana monitoring and a web dashboard. Unsampled subsystems are included where documented, but their internal links are limited to README evidence.

Main entry points: [`routers/task.py`](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/task.py) (Task API), [`main.py`](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/main.py) (FastAPI App), [`db/connection.py`](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py) (Tasks and History), [`routers/workers.py`](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/workers.py) (Worker API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["API Control Plane"]
  node_api["FastAPI App<br/>[main.py]"]
  node_task_api["Task API<br/>[task.py]"]
  node_worker_api["Worker API<br/>[workers.py]"]
  node_learning_api["Learning API<br/>[learning.py]"]
  node_models["Request and Task Models<br/>[model.py]"]
end

subgraph group_scheduling["Adaptive Scheduling"]
  node_estimator["Duration Estimator<br/>[estimator.py]"]
  node_rl_agent["Q-Learning Agent<br/>[rl_agent.py]"]
  node_learner["Background Learner<br/>[learner.py]"]
end

subgraph group_execution["Workers and Recovery"]
  node_worker_runtime["Worker Runtime<br/>[worker.py]"]
  node_heartbeat["Heartbeat Monitor<br/>[heartbeat.py]"]
  node_recovery["Task Recovery<br/>[recovery.py]"]
end

subgraph group_state["Persistent State"]
  node_mongo["MongoDB Access<br/>[connection.py]"]
  node_task_store[("Tasks and History<br/>[connection.py]")]
  node_worker_store[("Worker Records<br/>[connection.py]")]
  node_q_store[("Q-Table<br/>[connection.py]")]
end

subgraph group_observability["Monitoring and UI"]
  node_metrics["Prometheus Metrics<br/>[metrics.py]"]
  node_prometheus["Prometheus Scraper<br/>[prometheus.yml]"]
  node_grafana["Grafana Dashboards<br/>[dashboard.yml]"]
  node_frontend["Web Dashboard<br/>[index.html]"]
end

node_client(("Client"))

node_client -->|"submits tasks"| node_task_api
node_client -->|"registers workers"| node_worker_api
node_api -->|"routes requests"| node_task_api
node_api -->|"routes requests"| node_worker_api
node_api -->|"routes requests"| node_learning_api
node_api -->|"initializes"| node_mongo
node_api -->|"starts"| node_learner
node_task_api -->|"validates data"| node_models
node_worker_api -->|"validates data"| node_models
node_task_api -->|"reads and writes"| node_task_store
node_task_api -->|"claims capacity"| node_worker_store
node_task_api -->|"estimates duration"| node_estimator
node_task_api -->|"scores candidates"| node_rl_agent
node_task_api -->|"updates counters"| node_metrics
node_worker_api -->|"registers and updates"| node_worker_store
node_worker_runtime -->|"registers and heartbeats"| node_worker_api
node_worker_runtime -->|"pulls and reports"| node_task_api
node_heartbeat -->|"checks worker status"| node_worker_store
node_recovery -->|"resets timed-out tasks"| node_task_store
node_learning_api -->|"records outcomes"| node_task_store
node_learning_api -->|"estimates duration"| node_estimator
node_learning_api -->|"reads Q metrics"| node_q_store
node_estimator -->|"reads history"| node_task_store
node_learner -->|"reads training history"| node_task_store
node_learner -->|"updates policy"| node_rl_agent
node_rl_agent -->|"loads and saves"| node_q_store
node_mongo -->|"provides collection access"| node_task_store
node_mongo -->|"provides collection access"| node_worker_store
node_mongo -->|"provides collection access"| node_q_store
node_api -->|"exposes metrics"| node_metrics
node_prometheus -.->|"scrapes metrics"| node_api
node_grafana -.->|"visualizes metrics"| node_prometheus
node_frontend -.->|"uses dashboard APIs"| node_api

click node_api "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/main.py"
click node_task_api "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/task.py"
click node_worker_api "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/workers.py"
click node_learning_api "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/learning.py"
click node_models "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/models/model.py"
click node_worker_runtime "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/workers/worker.py"
click node_heartbeat "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/workers/heartbeat.py"
click node_recovery "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/recovery/recovery.py"
click node_estimator "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/scheduling/estimator.py"
click node_rl_agent "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/scheduling/rl_agent.py"
click node_learner "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/scheduling/learner.py"
click node_mongo "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py"
click node_task_store "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py"
click node_worker_store "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py"
click node_q_store "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py"
click node_metrics "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/core/metrics.py"
click node_prometheus "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/prometheus.yml"
click node_grafana "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/grafana/dashboards/dashboard.yml"
click node_frontend "https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/frontend/index.html"

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_api,node_task_api,node_worker_api,node_learning_api,node_models,node_client toneBlue
class node_estimator,node_rl_agent,node_learner toneAmber
class node_worker_runtime,node_heartbeat,node_recovery toneMint
class node_mongo,node_task_store,node_worker_store,node_q_store toneRose
class node_metrics,node_prometheus,node_grafana,node_frontend toneIndigo
```

## Components

### API Control Plane

- [FastAPI App](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/main.py): `main.py`
- [Task API](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/task.py): `routers/task.py`
- [Worker API](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/workers.py): `routers/workers.py`
- [Learning API](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/routers/learning.py): `routers/learning.py`
- [Request and Task Models](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/models/model.py): `models/model.py`

### Adaptive Scheduling

- [Duration Estimator](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/scheduling/estimator.py): `scheduling/estimator.py`
- [Q-Learning Agent](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/scheduling/rl_agent.py): `scheduling/rl_agent.py`
- [Background Learner](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/scheduling/learner.py): `scheduling/learner.py`

### Workers and Recovery

- [Worker Runtime](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/workers/worker.py): `workers/worker.py`
- [Heartbeat Monitor](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/workers/heartbeat.py): `workers/heartbeat.py`
- [Task Recovery](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/recovery/recovery.py): `recovery/recovery.py`

### Persistent State

- [MongoDB Access](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py): `db/connection.py`
- [Tasks and History](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py): `db/connection.py`
- [Worker Records](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py): `db/connection.py`
- [Q-Table](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/db/connection.py): `db/connection.py`

### Monitoring and UI

- [Prometheus Metrics](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/core/metrics.py): `core/metrics.py`
- [Prometheus Scraper](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/prometheus.yml): `prometheus.yml`
- [Grafana Dashboards](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/grafana/dashboards/dashboard.yml): `grafana/dashboards/dashboard.yml`
- [Web Dashboard](https://github.com/hrishikeshchandi/adaptive-rl-task-orchestrator/blob/main/frontend/index.html): `frontend/index.html`

### Other components

- **Client**

## Connections

- Client → Task API: submits tasks (evidence: `README.md`)
- Client → Worker API: registers workers (evidence: `README.md`)
- FastAPI App → Task API: routes requests (evidence: `main.py`)
- FastAPI App → Worker API: routes requests (evidence: `main.py`)
- FastAPI App → Learning API: routes requests (evidence: `main.py`)
- FastAPI App → MongoDB Access: initializes (evidence: `main.py`)
- FastAPI App → Background Learner: starts (evidence: `main.py`)
- Task API → Request and Task Models: validates data (evidence: `routers/task.py`)
- Worker API → Request and Task Models: validates data (evidence: `routers/workers.py`)
- Task API → Tasks and History: reads and writes (evidence: `routers/task.py`)
- Task API → Worker Records: claims capacity (evidence: `routers/task.py`)
- Task API → Duration Estimator: estimates duration (evidence: `routers/task.py`)
- Task API → Q-Learning Agent: scores candidates (evidence: `routers/task.py`)
- Task API → Prometheus Metrics: updates counters (evidence: `routers/task.py`)
- Worker API → Worker Records: registers and updates (evidence: `routers/workers.py`)
- Worker Runtime → Worker API: registers and heartbeats (evidence: `workers/worker.py`)
- Worker Runtime → Task API: pulls and reports (evidence: `workers/worker.py`)
- Heartbeat Monitor → Worker Records: checks worker status (evidence: `workers/heartbeat.py`)
- Task Recovery → Tasks and History: resets timed-out tasks (evidence: `recovery/recovery.py`)
- Learning API → Tasks and History: records outcomes (evidence: `routers/learning.py`)
- Learning API → Duration Estimator: estimates duration (evidence: `routers/learning.py`)
- Learning API → Q-Table: reads Q metrics (evidence: `routers/learning.py`)
- Duration Estimator → Tasks and History: reads history (evidence: `scheduling/estimator.py`)
- Background Learner → Tasks and History: reads training history (evidence: `scheduling/learner.py`)
- Background Learner → Q-Learning Agent: updates policy (evidence: `scheduling/learner.py`)
- Q-Learning Agent → Q-Table: loads and saves (evidence: `scheduling/rl_agent.py`)
- MongoDB Access → Tasks and History: provides collection access (evidence: `db/connection.py`)
- MongoDB Access → Worker Records: provides collection access (evidence: `db/connection.py`)
- MongoDB Access → Q-Table: provides collection access (evidence: `db/connection.py`)
- FastAPI App → Prometheus Metrics: exposes metrics (evidence: `main.py`)
- Prometheus Scraper → FastAPI App: scrapes metrics (evidence: `README.md`)
- Grafana Dashboards → Prometheus Scraper: visualizes metrics (evidence: `README.md`)
- Web Dashboard → FastAPI App: uses dashboard APIs (evidence: `README.md`)