# rajatsen91/ts-arena-models architecture

> Architecture diagram of the GitHub repository rajatsen91/ts-arena-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajatsen91/ts-arena-models
- Repository: https://github.com/rajatsen91/ts-arena-models

## Overview

1. **System purpose**
   TS-Models is not a single application; it is a **fleet of forecasting microservices** used to participate in TS-Arena time-series challenges. The repo provides model containers, a controller, and upload/registration utilities that together automate challenge participation.

2. **Top-level architecture**
   The repo is split into three main runtime layers:
   - **master-controller**: orchestration and request routing
   - **model-services**: one containerized inference service per forecasting model
   - **challenge-uploads**: registration/upload utilities for integrating with TS-Arena

3. **Control plane vs. model plane**
   The **master-controller** is the control plane. It likely accepts challenge tasks, decides which model service to invoke, and coordinates execution. The **model-services** are the data plane: each service encapsulates one forecasting backend and exposes a small API for predictions. This separation is the key architectural boundary.

4. **Per-model service pattern**
   Each folder under `model-services/` has the same shape: `Dockerfile`, `requirements.txt`, and an `app/` package with `main.py` and `model.py`. That suggests a **uniform service contract** across models, where `main.py` exposes the service endpoint and `model.py` contains the model-specific loading/inference logic.

5. **Model portfolio**
   The repository includes many independent forecasting implementations: Chronos, FlowState, Moirai, Moment, Naive Forecast, NeuralForecast, Seasonal Average, Simple Moving Average, Sundial, TabPFN-TS, Time-MoE, TimesFM, TimesFM2_5, TinyTimeMixer, Tirex, Toto, and VisionTS. Architecturally, these are **parallel plug-in services**, not libraries embedded in one process.

6. **Service startup and deployment model**
   Root-level Docker Compose files orchestrate the whole system. There is a base compose file plus environment-specific overlays for:
   - **GPU** deployments
   - **macOS** deployments
   - **CPU-only** deployments
   There are also per-model compose fragments under `compose/`, which indicates the stack can selectively build or start individual model services.

7. **On-demand execution flow**
   The README indicates a two-step flow: build/create all model containers first, then start only the controller and upload services. This implies the controller can **start model containers on demand** when a challenge arrives, rather than keeping every model hot in memory.

8. **Challenge ingestion and registration**
   The **challenge-uploads** component is a separate service for registering models with the arena. It has its own Dockerfile, requirements, config, and `main.py`, so it likely handles external platform interaction such as submitting service metadata, challenge enrollment, or upload tasks.

9. **Example / local test path**
   The `example/` directory mirrors the production setup with simplified compose files and an `example_usage.py` script. This is a separate **developer/test boundary** for local experimentation without full TS-Arena participation.

10. **Infrastructure assumptions**
   The stack is container-first and depends heavily on **Docker Compose**. GPU support is explicitly handled through compose overlays and `GPU_ID` configuration, so deployment topology matters: the same repo supports GPU, macOS, and CPU-only runtimes with different compose wiring.

11. **Data flow at runtime**
   The high-level runtime path is:
   **TS-Arena challenge event → master-controller → selected model-service container → forecast output → controller/upload path back to arena**.
   Ground truth arrives later from the arena, but that evaluation loop is outside this repository.

12. **What to draw in an architecture diagram**
   A good diagram should show:
   - one central **master-controller**
   - multiple **independent model-service containers**
   - a separate **challenge-uploads** integration component
   - **Docker Compose** as the deployment/orchestration layer
   - optional **GPU/CPU/macOS overlays**
   - an external boundary for **TS-Arena** as the upstream/downstream platform

13. **Overall design style**
   This is a **modular benchmark participation platform** rather than a monolith. The main architectural idea is standardization: every forecasting model is wrapped behind the same service boundary so the controller can treat them uniformly.

Main entry points: [`model-services/chronos/app/main.py`](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/chronos/app/main.py) (Model contract), [`master-controller/src/api.py`](https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/api.py) (Master controller), [`docker-compose.yml`](https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.yml) (Base compose), [`challenge-uploads/src/main.py`](https://github.com/rajatsen91/ts-arena-models/blob/main/challenge-uploads/src/main.py) (Upload service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External platform"]
  node_ts_arena{{"TS-Arena<br/>challenge platform"}}
end

subgraph group_deployment["Deployment"]
  node_compose_base["Base compose<br/>docker-compose<br/>[docker-compose.yml]"]
  node_compose_gpu["GPU overlay<br/>compose overlay"]
  node_compose_macos["macOS overlay<br/>compose overlay"]
  node_compose_cpu["CPU overlay<br/>compose overlay<br/>[docker-compose.yml]"]
end

subgraph group_control["Control plane"]
  node_master_controller["Master controller<br/>orchestrator<br/>[api.py]"]
  node_controller_worker["Worker<br/>[worker.py]"]
  node_controller_config["Config<br/>[config.py]"]
end

subgraph group_models["Model plane"]
  node_model_contract["Model contract<br/>service pattern<br/>[main.py]"]
  node_chronos_service["Chronos<br/>forecast service<br/>[main.py]"]
  node_moirai_service["Moirai<br/>forecast service<br/>[main.py]"]
  node_timesfm_service["TimesFM<br/>forecast service<br/>[main.py]"]
  node_tinemix_service["TinyTimeMixer<br/>forecast service<br/>[main.py]"]
  node_statistical_service["Statistical<br/>forecast service<br/>[main.py]"]
  node_other_models["Other models<br/>model fleet"]
end

subgraph group_integration["Integration"]
  node_challenge_uploads["Upload service<br/>integration service<br/>[main.py]"]
  node_upload_config["Upload config<br/>integration config<br/>[config.json]"]
end

subgraph group_example["Example"]
  node_example_stack["Example stack<br/>local demo<br/>[docker-compose.yml]"]
  node_example_usage["Example usage<br/>demo script<br/>[example_usage.py]"]
end

node_compose_base -->|"starts"| node_master_controller
node_compose_base -->|"builds"| node_model_contract
node_compose_gpu -.->|"overrides"| node_compose_base
node_compose_macos -.->|"overrides"| node_compose_base
node_compose_cpu -.->|"overrides"| node_compose_base
node_master_controller -->|"delegates"| node_controller_worker
node_master_controller -->|"reads"| node_controller_config
node_master_controller -->|"routes to"| node_model_contract
node_model_contract -->|"implements"| node_chronos_service
node_model_contract -->|"implements"| node_moirai_service
node_model_contract -->|"implements"| node_timesfm_service
node_model_contract -->|"implements"| node_tinemix_service
node_model_contract -->|"implements"| node_statistical_service
node_model_contract -->|"covers"| node_other_models
node_challenge_uploads -->|"reads"| node_upload_config
node_challenge_uploads -->|"registers with"| node_ts_arena
node_master_controller -->|"coordinates"| node_challenge_uploads
node_example_stack -.->|"mirrors"| node_master_controller
node_example_stack -.->|"mirrors"| node_model_contract
node_example_usage -->|"drives"| node_example_stack

click node_compose_base "https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.yml"
click node_compose_gpu "https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.gpu.yml"
click node_compose_macos "https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.macos.yml"
click node_compose_cpu "https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.yml"
click node_master_controller "https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/api.py"
click node_controller_worker "https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/worker.py"
click node_controller_config "https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/config.py"
click node_model_contract "https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/chronos/app/main.py"
click node_chronos_service "https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/chronos/app/main.py"
click node_moirai_service "https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/moirai/app/main.py"
click node_timesfm_service "https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/timesfm/app/main.py"
click node_tinemix_service "https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/tinytimemixer/app/main.py"
click node_statistical_service "https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/seasonal-average/app/main.py"
click node_challenge_uploads "https://github.com/rajatsen91/ts-arena-models/blob/main/challenge-uploads/src/main.py"
click node_upload_config "https://github.com/rajatsen91/ts-arena-models/blob/main/challenge-uploads/src/config.json"
click node_example_stack "https://github.com/rajatsen91/ts-arena-models/blob/main/example/docker-compose.yml"
click node_example_usage "https://github.com/rajatsen91/ts-arena-models/blob/main/example/example_usage.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_ts_arena toneBlue
class node_compose_base,node_compose_gpu,node_compose_macos,node_compose_cpu toneAmber
class node_master_controller,node_controller_worker,node_controller_config toneMint
class node_model_contract,node_chronos_service,node_moirai_service,node_timesfm_service,node_tinemix_service,node_statistical_service,node_other_models toneRose
class node_challenge_uploads,node_upload_config toneIndigo
class node_example_stack,node_example_usage toneTeal
```

## Components

### External platform

TS-Arena challenge environment outside this repository

- **TS-Arena**: challenge platform · Upstream/downstream arena that sends tasks and receives submissions

### Deployment

Docker Compose layers and runtime overlays

- [Base compose](https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.yml): docker-compose · Core stack wiring for controller and services · `docker-compose.yml`
- [GPU overlay](https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.gpu.yml): compose overlay · GPU-specific runtime wiring · `docker-compose.gpu.yml`
- [macOS overlay](https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.macos.yml): compose overlay · macOS-specific runtime wiring · `docker-compose.macos.yml`
- [CPU overlay](https://github.com/rajatsen91/ts-arena-models/blob/main/docker-compose.yml): compose overlay · CPU-only runtime wiring · `docker-compose.yml`

### Control plane

Orchestration and routing for challenge handling

- [Master controller](https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/api.py): orchestrator · Central control plane for routing and execution · `master-controller/src/api.py`
- [Worker](https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/worker.py): execution worker · Background coordination and task handling logic · `master-controller/src/worker.py`
- [Config](https://github.com/rajatsen91/ts-arena-models/blob/main/master-controller/src/config.py): controller config · Controller runtime settings and environment handling · `master-controller/src/config.py`

### Model plane

Containerized forecasting services with a shared contract

- [Model contract](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/chronos/app/main.py): service pattern · Shared service shape used by every model container · `model-services/chronos/app/main.py`
- [Chronos](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/chronos/app/main.py): forecast service · Representative forecasting container · `model-services/chronos/app/main.py`
- [Moirai](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/moirai/app/main.py): forecast service · Representative forecasting container · `model-services/moirai/app/main.py`
- [TimesFM](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/timesfm/app/main.py): forecast service · Representative forecasting container · `model-services/timesfm/app/main.py`
- [TinyTimeMixer](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/tinytimemixer/app/main.py): forecast service · Representative forecasting container · `model-services/tinytimemixer/app/main.py`
- [Statistical](https://github.com/rajatsen91/ts-arena-models/blob/main/model-services/seasonal-average/app/main.py): forecast service · Representative lightweight baseline services · `model-services/seasonal-average/app/main.py`
- **Other models**: model fleet · Additional plug-in forecasting services such as FlowState, Moment, NeuralForecast, Sundial, TabPFN-TS, Time-MoE, TimesFM2.5, Tirex, Toto, VisionTS, and Naive/SMA baselines

### Integration

Challenge registration and upload utilities

- [Upload service](https://github.com/rajatsen91/ts-arena-models/blob/main/challenge-uploads/src/main.py): integration service · Registration and upload utility for arena integration · `challenge-uploads/src/main.py`
- [Upload config](https://github.com/rajatsen91/ts-arena-models/blob/main/challenge-uploads/src/config.json): integration config · Upload service settings and arena metadata · `challenge-uploads/src/config.json`

### Example

Local developer/test setup

- [Example stack](https://github.com/rajatsen91/ts-arena-models/blob/main/example/docker-compose.yml): local demo · Simplified compose-based local setup for experimentation · `example/docker-compose.yml`
- [Example usage](https://github.com/rajatsen91/ts-arena-models/blob/main/example/example_usage.py): demo script · Local walkthrough and invocation example · `example/example_usage.py`

## Connections

- Base compose → Master controller: starts · Base compose wires up the control plane
- Base compose → Model contract: builds · Base compose includes model service containers
- GPU overlay → Base compose: overrides · GPU deployment adds runtime-specific wiring
- macOS overlay → Base compose: overrides · macOS deployment adds runtime-specific wiring
- CPU overlay → Base compose: overrides · CPU deployment adds runtime-specific wiring
- Master controller → Worker: delegates · API layer hands execution to worker logic
- Master controller → Config: reads · Controller behavior is driven by config
- Master controller → Model contract: routes to · Controller invokes the shared model-service API
- Model contract → Chronos: implements · One of the standard forecasting service instances
- Model contract → Moirai: implements · One of the standard forecasting service instances
- Model contract → TimesFM: implements · One of the standard forecasting service instances
- Model contract → TinyTimeMixer: implements · One of the standard forecasting service instances
- Model contract → Statistical: implements · Representative baseline service family
- Model contract → Other models: covers · Remaining forecasting containers follow the same pattern
- Upload service → Upload config: reads · Upload flow is driven by service metadata
- Upload service → TS-Arena: registers with · Submits models or service metadata to the arena
- Master controller → Upload service: coordinates · Controller and upload service work together for challenge participation
- Example stack → Master controller: mirrors · Example deployment mirrors the production controller
- Example stack → Model contract: mirrors · Example deployment mirrors the model-service pattern
- Example usage → Example stack: drives · Script demonstrates the local example setup