# imosudi/resimhub architecture

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

- Interactive diagram: https://gitdiagram.com/imosudi/resimhub
- Repository: https://github.com/imosudi/resimhub

## Overview

ReSimHub is a hybrid Flask/FastAPI backend for managing RL experiments, environments, training runs, and agent benchmarks. The main workflow is a client request into FastAPI, asynchronous training dispatch through Celery, progress/status reporting, and persisted run history; separate APIs support evaluation, analytics, metrics, and dashboards. Flask provides a legacy gateway/bridge. The README also documents Prometheus/Grafana observability and distributed Redis/Celery capabilities. Some routers and integrations are unsampled, so their internal links are omitted or marked unverified.

Main entry points: [`backend/fastapi_app/main.py`](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/main.py) (FastAPI Entry), [`backend/fastapi_app/services/orchestrator.py`](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/orchestrator.py) (Training Worker), [`backend/fastapi_app/core/db.py`](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/core/db.py) (SQL Database), [`backend/fastapi_app/routers/orchestrator.py`](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/orchestrator.py) (Training API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Services"]
  node_fastapi["FastAPI Entry<br/>[main.py]"]
  node_flask["Flask Gateway<br/>[__init__.py]"]
  node_flask_bridge["Training Bridge<br/>[training_bridge.py]"]
  node_api_proxy["API Proxy<br/>[api_proxy.py]"]
end

subgraph group_research["Experiment Workflow"]
  node_experiments["Experiment API<br/>[experiments.py]"]
  node_environments["Environment API<br/>[environments.py]"]
  node_experiment_models["Experiment Models"]
end

subgraph group_execution["Training Execution"]
  node_training_api["Training API<br/>[orchestrator.py]"]
  node_training_service["Training Worker<br/>[orchestrator.py]"]
  node_progress["Progress Broadcast"]
  node_training_runs["Training Run Model<br/>[training_model.py]"]
  node_train_routes["Train Routes<br/>[train.py]"]
  node_status_routes["Task Status Routes<br/>[status.py]"]
end

subgraph group_evaluation["Evaluation Analytics"]
  node_benchmark_api["Benchmark API<br/>[benchmark.py]"]
  node_benchmark_service["Benchmark Service"]
  node_benchmark_models["Benchmark Models<br/>[benchmark_model.py]"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
  node_analytics_service["Analytics Service"]
  node_metrics_api["Metrics API<br/>[metrics.py]"]
  node_dashboard["Dashboard API<br/>[dashboard.py]"]
end

subgraph group_platform["State And Observability"]
  node_database[("SQL Database<br/>[db.py]")]
  node_config["Configuration<br/>[config.py]"]
  node_redis[("Redis")]
  node_celery["Celery Queue"]
  node_prometheus["Prometheus / Grafana"]
end

node_client(("REST Client"))

node_client -->|"sends requests"| node_fastapi
node_fastapi -->|"registers router"| node_experiments
node_fastapi -->|"registers router"| node_environments
node_fastapi -->|"registers router"| node_training_api
node_fastapi -->|"registers router"| node_train_routes
node_fastapi -->|"registers router"| node_status_routes
node_fastapi -->|"registers router"| node_benchmark_api
node_fastapi -->|"registers router"| node_analytics_api
node_fastapi -->|"registers router"| node_metrics_api
node_fastapi -->|"registers router"| node_dashboard
node_fastapi -->|"initializes"| node_database
node_fastapi -->|"connects at startup"| node_progress
node_experiments -->|"uses models"| node_experiment_models
node_experiments -->|"accesses sessions"| node_database
node_environments -->|"uses models"| node_experiment_models
node_environments -->|"accesses sessions"| node_database
node_training_api -->|"queues task"| node_training_service
node_training_api -->|"records queued run"| node_training_runs
node_training_api -->|"subscribes to updates"| node_progress
node_training_service -->|"dispatches tasks"| node_celery
node_training_service -->|"publishes progress"| node_redis
node_training_service -->|"persists run state"| node_database
node_progress -->|"publishes and subscribes"| node_redis
node_status_routes -->|"checks task status"| node_training_service
node_train_routes -->|"uses task service"| node_training_service
node_benchmark_api -.->|"uses evaluator"| node_benchmark_service
node_benchmark_service -->|"persists evaluation"| node_benchmark_models
node_benchmark_service -->|"reads and writes"| node_database
node_benchmark_service -->|"caches results"| node_redis
node_analytics_api -->|"uses service"| node_analytics_service
node_dashboard -->|"uses broadcaster"| node_progress
node_flask -->|"registers routes"| node_flask_bridge
node_flask_bridge -->|"delegates requests"| node_api_proxy
node_config -->|"configures connection"| node_database
node_client -.->|"uses gateway"| node_flask
node_prometheus -.->|"observes metrics"| node_metrics_api

click node_fastapi "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/main.py"
click node_flask "https://github.com/imosudi/resimhub/blob/main/backend/flask_app/__init__.py"
click node_flask_bridge "https://github.com/imosudi/resimhub/blob/main/backend/flask_app/routes/training_bridge.py"
click node_api_proxy "https://github.com/imosudi/resimhub/blob/main/backend/flask_app/services/api_proxy.py"
click node_experiments "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/experiments.py"
click node_environments "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/environments.py"
click node_experiment_models "https://github.com/imosudi/resimhub/blob/main/shared/models/experiment_model.py"
click node_training_api "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/orchestrator.py"
click node_training_service "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/orchestrator.py"
click node_progress "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/progress_broadcast.py"
click node_training_runs "https://github.com/imosudi/resimhub/blob/main/shared/models/training_model.py"
click node_train_routes "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/train.py"
click node_status_routes "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/status.py"
click node_benchmark_api "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/benchmark.py"
click node_benchmark_service "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/benchmark_service.py"
click node_benchmark_models "https://github.com/imosudi/resimhub/blob/main/shared/models/benchmark_model.py"
click node_analytics_api "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/analytics.py"
click node_analytics_service "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/analytics_service.py"
click node_metrics_api "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/metrics.py"
click node_dashboard "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/dashboard.py"
click node_database "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/core/db.py"
click node_config "https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/core/config.py"

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_fastapi,node_flask,node_flask_bridge,node_api_proxy,node_client toneBlue
class node_experiments,node_environments,node_experiment_models toneAmber
class node_training_api,node_training_service,node_progress,node_training_runs,node_train_routes,node_status_routes toneMint
class node_benchmark_api,node_benchmark_service,node_benchmark_models,node_analytics_api,node_analytics_service,node_metrics_api,node_dashboard toneRose
class node_database,node_config,node_redis,node_celery,node_prometheus toneIndigo
```

## Components

### API Services

- [FastAPI Entry](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/main.py): `backend/fastapi_app/main.py`
- [Flask Gateway](https://github.com/imosudi/resimhub/blob/main/backend/flask_app/__init__.py): `backend/flask_app/__init__.py`
- [Training Bridge](https://github.com/imosudi/resimhub/blob/main/backend/flask_app/routes/training_bridge.py): `backend/flask_app/routes/training_bridge.py`
- [API Proxy](https://github.com/imosudi/resimhub/blob/main/backend/flask_app/services/api_proxy.py): `backend/flask_app/services/api_proxy.py`

### Experiment Workflow

- [Experiment API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/experiments.py): `backend/fastapi_app/routers/experiments.py`
- [Environment API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/environments.py): `backend/fastapi_app/routers/environments.py`
- [Experiment Models](https://github.com/imosudi/resimhub/blob/main/shared/models/experiment_model.py): `shared/models/experiment_model.py`

### Training Execution

- [Training API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/orchestrator.py): `backend/fastapi_app/routers/orchestrator.py`
- [Training Worker](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/orchestrator.py): `backend/fastapi_app/services/orchestrator.py`
- [Progress Broadcast](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/progress_broadcast.py): `backend/fastapi_app/services/progress_broadcast.py`
- [Training Run Model](https://github.com/imosudi/resimhub/blob/main/shared/models/training_model.py): `shared/models/training_model.py`
- [Train Routes](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/train.py): `backend/fastapi_app/routers/train.py`
- [Task Status Routes](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/status.py): `backend/fastapi_app/routers/status.py`

### Evaluation Analytics

- [Benchmark API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/benchmark.py): `backend/fastapi_app/routers/benchmark.py`
- [Benchmark Service](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/benchmark_service.py): `backend/fastapi_app/services/benchmark_service.py`
- [Benchmark Models](https://github.com/imosudi/resimhub/blob/main/shared/models/benchmark_model.py): `shared/models/benchmark_model.py`
- [Analytics API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/analytics.py): `backend/fastapi_app/routers/analytics.py`
- [Analytics Service](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/services/analytics_service.py): `backend/fastapi_app/services/analytics_service.py`
- [Metrics API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/metrics.py): `backend/fastapi_app/routers/metrics.py`
- [Dashboard API](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/routers/dashboard.py): `backend/fastapi_app/routers/dashboard.py`

### State And Observability

- [SQL Database](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/core/db.py): `backend/fastapi_app/core/db.py`
- [Configuration](https://github.com/imosudi/resimhub/blob/main/backend/fastapi_app/core/config.py): `backend/fastapi_app/core/config.py`
- **Redis**
- **Celery Queue**
- **Prometheus / Grafana**

### Other components

- **REST Client**

## Connections

- REST Client → FastAPI Entry: sends requests (evidence: `README.md`)
- FastAPI Entry → Experiment API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Environment API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Training API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Train Routes: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Task Status Routes: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Benchmark API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Analytics API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Metrics API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Dashboard API: registers router (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → SQL Database: initializes (evidence: `backend/fastapi_app/main.py`)
- FastAPI Entry → Progress Broadcast: connects at startup (evidence: `backend/fastapi_app/main.py`)
- Experiment API → Experiment Models: uses models (evidence: `backend/fastapi_app/routers/experiments.py`)
- Experiment API → SQL Database: accesses sessions (evidence: `backend/fastapi_app/routers/experiments.py`)
- Environment API → Experiment Models: uses models (evidence: `backend/fastapi_app/routers/environments.py`)
- Environment API → SQL Database: accesses sessions (evidence: `backend/fastapi_app/routers/environments.py`)
- Training API → Training Worker: queues task (evidence: `backend/fastapi_app/routers/orchestrator.py`)
- Training API → Training Run Model: records queued run (evidence: `backend/fastapi_app/routers/orchestrator.py`)
- Training API → Progress Broadcast: subscribes to updates (evidence: `backend/fastapi_app/routers/orchestrator.py`)
- Training Worker → Celery Queue: dispatches tasks (evidence: `README.md`)
- Training Worker → Redis: publishes progress (evidence: `backend/fastapi_app/services/orchestrator.py`)
- Training Worker → SQL Database: persists run state (evidence: `backend/fastapi_app/services/orchestrator.py`)
- Progress Broadcast → Redis: publishes and subscribes (evidence: `backend/fastapi_app/services/progress_broadcast.py`)
- Task Status Routes → Training Worker: checks task status (evidence: `backend/fastapi_app/routers/status.py`)
- Train Routes → Training Worker: uses task service (evidence: `backend/fastapi_app/routers/train.py`)
- Benchmark API → Benchmark Service: uses evaluator
- Benchmark Service → Benchmark Models: persists evaluation (evidence: `backend/fastapi_app/services/benchmark_service.py`)
- Benchmark Service → SQL Database: reads and writes (evidence: `backend/fastapi_app/services/benchmark_service.py`)
- Benchmark Service → Redis: caches results (evidence: `backend/fastapi_app/services/benchmark_service.py`)
- Analytics API → Analytics Service: uses service (evidence: `backend/fastapi_app/routers/analytics.py`)
- Dashboard API → Progress Broadcast: uses broadcaster (evidence: `backend/fastapi_app/routers/dashboard.py`)
- Flask Gateway → Training Bridge: registers routes (evidence: `backend/flask_app/__init__.py`)
- Training Bridge → API Proxy: delegates requests (evidence: `backend/flask_app/routes/training_bridge.py`)
- Configuration → SQL Database: configures connection (evidence: `backend/fastapi_app/core/db.py`)
- REST Client → Flask Gateway: uses gateway (evidence: `README.md`)
- Prometheus / Grafana → Metrics API: observes metrics (evidence: `README.md`)
