rajatsen91/ts-arena-models

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.