# microprediction/timemachines architecture

> Architecture diagram of the GitHub repository microprediction/timemachines, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microprediction/timemachines
- Repository: https://github.com/microprediction/timemachines

## Overview

##### Project type and purpose
- This is an open-source Python library (“timemachines”) providing a uniform, pure-function API for univariate time-series forecasting.
- It wraps many external forecasting engines (“skaters”)—e.g. statsmodels, Prophet, Darts—behind a consistent interface for benchmarking, ensemble, composition, etc.

##### High-level architectural components
a. Core API layer
- entrypoint module (timemachines/skating.py)
- interface contract for all skaters: f(y, s, k, a, t, e, r) → (xt, xt_std, s′)
b. Skater inclusion layer
- timemachines/inclusion: adapters that import and configure external packages
- each inclusion module registers functions and default hyper-parameters
c. Skater implementations
- timemachines/skaters: subpackages per engine (ats, bats, divine, dlm, darts, etc.)
- factory modules (…factory.py) and collections (all<engine>skaters.py)
d. Supporting toolkits
- timemachines/skatertools: batch processing, combining forecasts, sampling, tuning, visualization
e. Examples & documentation
- examples/: runnable demos organized by use-case
- docs/: static site source, assets, articles
f. Tests & CI
- tests/: per-engine and core tests ensuring integration and correctness
- .github/workflows/, .travis.yml: automated testing across external dependencies
g. Packaging
- setup.py, requirements.txt, INSTALL.md
- CONTRIBUTION guides, license, README

##### Relationships & data flow
- User code → Core API (skating.py)
- Core API calls one or more skater implementations
- Each skater module imports its inclusion adapter to interface with the external library
- Outputs propagated back to the user
- Skatertools can wrap sets of skaters for ensembling, tuning, evaluation
- CI pipelines trigger tests across all external backends

##### Architectural patterns & design principles
- Plugin/adaptor pattern: each external package is wrapped by an inclusion module
- Stateless functional API: each call passes in state, returns new state
- Factory pattern: central registry of available skaters, dynamically instantiated
- Separation of concerns: core interface, inclusion adapters, skater logic, utilities, tests, docs

##### Details
- Don’t omit the dynamic factory/registry in timemachines/skaters/allskaters.py
- Functional-stateless pattern (state in → state out)
- How new inclusion modules drop into timemachines/inclusion for plugin discovery

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Internal Components"
        CoreAPI["Core API"]:::core
        Inclusion["Inclusion Adapters"]:::core
        subgraph "Skater Implementations"
            AllSkaters["Registry/Factory"]:::core
            ATS["ATS Inclusion"]:::core
            BATS["BATS Factory"]:::core
        end
        Skatertools["Skatertools"]:::core
    end

    subgraph "External Dependencies"
        ExternalPackages["External Forecast Engines"]:::external
    end

    subgraph "Infrastructure"
        Examples["Examples"]:::infra
        Docs["Docs"]:::infra
        Tests["Tests"]:::infra
        CIWorkflows["CI Workflows"]:::infra
        TravisCI["Travis CI"]:::infra
        Packaging["Packaging & Metadata"]:::infra
    end

    CoreAPI -->|"calls"| Inclusion
    Inclusion -->|"wraps"| ExternalPackages
    CoreAPI -->|"dispatches"| AllSkaters
    AllSkaters -->|"includes"| ATS
    AllSkaters -->|"includes"| BATS
    ATS -->|"uses adapter"| Inclusion
    BATS -->|"uses adapter"| Inclusion
    CoreAPI -->|"provides tools"| Skatertools
    CoreAPI -->|"demonstrated in"| Examples
    CoreAPI -->|"documented in"| Docs
    CIWorkflows -->|"runs tests in"| Tests
    TravisCI -->|"runs tests in"| Tests
    Tests -->|"validate"| CoreAPI
    Tests -->|"validate"| AllSkaters
    Tests -->|"validate"| ATS
    Tests -->|"validate"| BATS

    click CoreAPI "https://github.com/microprediction/timemachines/blob/main/timemachines/skating.py"
    click Inclusion "https://github.com/microprediction/timemachines/tree/main/timemachines/inclusion/"
    click AllSkaters "https://github.com/microprediction/timemachines/blob/main/timemachines/skaters/allskaters.py"
    click ATS "https://github.com/microprediction/timemachines/blob/main/timemachines/skaters/ats/atsinclusion.py"
    click BATS "https://github.com/microprediction/timemachines/blob/main/timemachines/skaters/bats/batsfactory.py"
    click Skatertools "https://github.com/microprediction/timemachines/tree/main/timemachines/skatertools/"
    click Examples "https://github.com/microprediction/timemachines/tree/main/examples/"
    click Docs "https://github.com/microprediction/timemachines/tree/main/docs/"
    click Tests "https://github.com/microprediction/timemachines/tree/main/tests/"
    click CIWorkflows "https://github.com/microprediction/timemachines/blob/main/.github/workflows/python-package.yml"
    click TravisCI "https://github.com/microprediction/timemachines/blob/main/.travis.yml"
    click Packaging "https://github.com/microprediction/timemachines/blob/main/setup.py"

    classDef core fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef external fill:#d4edda,stroke:#28a745,color:#28a745
    classDef infra fill:#ffe5b4,stroke:#e36209,color:#e36209
```
