# pysport/kloppy architecture

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

- Interactive diagram: https://gitdiagram.com/pysport/kloppy
- Repository: https://github.com/pysport/kloppy

## Overview

##### Project Type & Purpose
- This is an open‐source library (toolkit) for processing soccer data.
- Its key functions include loading data from multiple providers (e.g., OPTA, StatsBomb, Wyscout, etc.), converting them into a standardized internal format, and providing data transformation and pattern matching functionality.
- The README emphasizes standard models, (de)serialization, data processing (pitch transformation, orientation shifting), and pattern matching in event data.

##### Analyzing the File Structure
- The main code lives under the “kloppy” directory.
- There is a clear modular separation:
– The “_providers” subdirectory holds provider-specific loading logic.
– The “domain” directory contains the standardized data models and domain services (aggregators, event factories, state builders, etc.).
– The “infra” layer represents input/output (IO) adapters and serializers. Under “infra/io/adapters,” there are adapters for file, HTTP, S3, and ZIP, indicating support for different data sources.
– The “infra/serializers” directories are divided into submodules such as “code” and “event” (with further segregation by vendor) along with “tracking” serializers.
- There are testing and examples directories that exemplify usage, as well as documentation files that provide additional context.

##### High-Level System Components
a. Data Input Sources:
– External data sources (files, HTTP endpoints, S3 buckets) that supply raw soccer tracking/event data.
b. IO/Adapter Layer:
– IO adapters under “kloppy/infra/io/adapters” handle data ingestion. Represent these as modules dedicated to file, HTTP, S3, and ZIP access.
c. Deserialization and Serialization Layer:
– Under “kloppy/infra/serializers” are vendor-specific deserializers for event data (for example in folders like “metrica,” “opta,” “statsbomb,” “wyscout,” etc.) and equivalent logic for tracking data.
d. Provider Abstraction:
– In “kloppy/_providers,” each provider (datafactory, hawkeye, metrica, etc.) encapsulates logic to interface with specific vendor formats.
e. Domain Model & Service Layer:
– Domain models (within “kloppy/domain/models”) standardize entities like Event, Formation, Position, etc.
– Domain services (found in “kloppy/domain/services”) include factories, aggregators, pattern matching services (for instance, the “pattern matching” and “state builder” components).
f. Processing and Transformation Components:
– Services that transform datasets (changing pitch dimensions, orientation, etc.) and execute pattern matching to extract meaningful fragments.
g. CLI Tooling & Utilities:
– The “kloppy/cmdline.py”, “helpers.py”, and similar utilities support running commands directly from the command line.

##### Relationships & Data Flow
- Data flows from external sources into the IO adapter layer.
- The adapters pass raw data to the appropriate serializer/deserializer based on the vendor/data format.
- The deserialized data is then converted into the standardized domain models.
- Domain services further process this data (aggregators, state builders, event factories, etc.) and make it available for downstream applications or integrations.
- Optionally, utilities and CLI commands provide interfaces to invoke this pipeline.

##### Architectural Patterns & Design Principles
- Modularity: Each vendor or functionality is isolated in its submodule (e.g., different serializers and domain services).
- Abstraction: The provider layer abstracts vendor specifics, while the domain layer offers a standardized representation of soccer data.
- Separation of Concerns: IO handling, data transformation, and domain logic are distinct.
- Extensibility: It is straightforward to add new providers or processing logics given the clear separation between the adapters, serializers, and domain services.

##### Relevant Technologies and Libraries
- Python is the core language.
- Although not explicitly a web application, it relies on standard Python packaging and build tools (setup.py, pyproject.toml) along with CI/CD (GitHub workflows under .github/workflows).
- The project also includes notebooks and examples (Jupyter notebooks in docs/examples and docs/getting-started) to illustrate usage.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Layer 1: Data Sources
    subgraph "Layer 1: Data Sources"
        DS["Data Input Sources (Files,HTTP,S3,ZIP,...)"]:::source
    end

    %% Layer 2: IO Adapters
    subgraph "Layer 2: IO Adapters"
        FA["File Adapter"]:::adapter
        HA["HTTP Adapter"]:::adapter
        SA["S3 Adapter"]:::adapter
        ZA["ZIP Adapter"]:::adapter
        FSA["Fsspec Adapter"]:::adapter
    end

    %% Layer 3: Deserializers and Serializers
    subgraph "Layer 3: Deserializers and Serializers"
        subgraph "Event Deserializers"
            DFD["Datafactory Deserializer"]:::deserializer
            MD["Metrica Event Deserializer"]:::deserializer
            SD["Sportec Event Deserializer"]:::deserializer
            STB["Statsbomb Deserializer"]:::deserializer
            STP["Statsperform Deserializer"]:::deserializer
            W2["Wyscout Deserializer v2"]:::deserializer
            W3["Wyscout Deserializer v3"]:::deserializer
        end
        subgraph "Tracking Deserializers"
            HD["Hawkeye Deserializer"]:::deserializer
            MC["Metrica CSV Deserializer"]:::deserializer
            ME["Metrica EPTS Deserializer"]:::deserializer
            PD["PFF Deserializer"]:::deserializer
            SSD["Secondspectrum Deserializer"]:::deserializer
            SKD["Skillcorner Deserializer"]:::deserializer
            STD["Sportec Tracking Deserializer"]:::deserializer
            STPD["Statsperform Tracking Deserializer"]:::deserializer
            TD["Tracab Deserializers"]:::deserializer
        end
        subgraph "Code Serializers"
            BCS["Base Code Serializer"]:::deserializer
            SCS["Sportscode Serializer"]:::deserializer
        end
    end

    %% Layer 4: Provider Abstraction
    subgraph "Layer 4: Provider Abstraction"
        Providers["Providers"]:::provider
    end

    %% Layer 5: Domain Models & Services
    subgraph "Layer 5: Domain Models & Services"
        DM["Domain Models"]:::domain
        DSrv["Domain Services"]:::domain
        subgraph "Domain Services Details"
            Agg["Aggregators"]:::domain
            Fact["Factories"]:::domain
            PM["PatternMatching"]:::domain
            SB["StateBuilders"]:::domain
            Trans["Transformers"]:::domain
        end
    end

    %% Layer 6: CLI & Utilities
    subgraph "Layer 6: CLI & Utilities"
        CLI["CommandLineInterface"]:::cli
        Helpers["HelperUtilities"]:::cli
        Config["Configuration"]:::cli
    end

    %% Data Flow Connections
    DS --> FA
    DS --> HA
    DS --> SA
    DS --> ZA
    DS --> FSA

    %% IO Adapters to Deserializers (representative flow)
    FA --> DFD
    FA --> HD
    HA --> MD
    HA --> MC
    SA --> PD
    ZA --> SSD
    FSA --> ME

    %% Deserializers feed into Providers
    DFD --- Providers
    MD --- Providers
    SD --- Providers
    STB --- Providers
    STP --- Providers
    W2 --- Providers
    W3 --- Providers
    HD --- Providers
    MC --- Providers
    ME --- Providers
    PD --- Providers
    SSD --- Providers
    SKD --- Providers
    STD --- Providers
    STPD --- Providers
    TD --- Providers
    BCS --- Providers
    SCS --- Providers

    %% Providers to Domain Models & Services
    Providers --> DM
    DM --> DSrv

    %% Domain Services internal breakdown
    DSrv --> Agg
    DSrv --> Fact
    DSrv --> PM
    DSrv --> SB
    DSrv --> Trans

    %% Integration with CLI & Utilities
    DSrv --> CLI
    DM --> CLI
    Helpers --> CLI
    Config --> CLI
    CLI --> Providers

    %% Style Definitions
    classDef source fill:#e0e0e0,stroke:#000,stroke-width:1.5px;
    classDef adapter fill:#a2d2ff,stroke:#000,stroke-width:1.5px;
    classDef deserializer fill:#ffbf9b,stroke:#000,stroke-width:1.5px;
    classDef provider fill:#caffbf,stroke:#000,stroke-width:1.5px;
    classDef domain fill:#d0bfff,stroke:#000,stroke-width:1.5px;
    classDef cli fill:#ffadad,stroke:#000,stroke-width:1.5px;

    %% Click Events for IO/Adapters
    click FA "https://github.com/pysport/kloppy/blob/master/kloppy/infra/io/adapters/file.py"
    click HA "https://github.com/pysport/kloppy/blob/master/kloppy/infra/io/adapters/http.py"
    click SA "https://github.com/pysport/kloppy/blob/master/kloppy/infra/io/adapters/s3.py"
    click ZA "https://github.com/pysport/kloppy/blob/master/kloppy/infra/io/adapters/zip.py"
    click FSA "https://github.com/pysport/kloppy/blob/master/kloppy/infra/io/adapters/fsspec.py"

    %% Click Events for Event Deserializers
    click DFD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/datafactory/deserializer.py"
    click MD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/metrica/json_deserializer.py"
    click SD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/sportec/deserializer.py"
    click STB "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/statsbomb/deserializer.py"
    click STP "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/statsperform/deserializer.py"
    click W2 "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/wyscout/deserializer_v2.py"
    click W3 "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/event/wyscout/deserializer_v3.py"

    %% Click Events for Tracking Deserializers
    click HD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/hawkeye/deserializer.py"
    click MC "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/metrica_csv.py"
    click ME "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/metrica_epts/deserializer.py"
    click PD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/pff.py"
    click SSD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/secondspectrum.py"
    click SKD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/skillcorner.py"
    click STD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/sportec/deserializer.py"
    click STPD "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/tracking/statsperform.py"
    click TD "https://github.com/pysport/kloppy/tree/master/kloppy/infra/serializers/tracking/tracab/"

    %% Click Events for Code Serializers
    click BCS "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/code/base.py"
    click SCS "https://github.com/pysport/kloppy/blob/master/kloppy/infra/serializers/code/sportscode.py"

    %% Click Event for Provider Abstraction
    click Providers "https://github.com/pysport/kloppy/tree/master/kloppy/_providers/"

    %% Click Events for Domain Models & Services
    click DM "https://github.com/pysport/kloppy/tree/master/kloppy/domain/models/"
    click Agg "https://github.com/pysport/kloppy/tree/master/kloppy/domain/services/aggregators/"
    click Fact "https://github.com/pysport/kloppy/blob/master/kloppy/domain/services/event_factory.py"
    click Fact "https://github.com/pysport/kloppy/blob/master/kloppy/domain/services/frame_factory.py"
    click PM "https://github.com/pysport/kloppy/tree/master/kloppy/domain/services/matchers/"
    click SB "https://github.com/pysport/kloppy/tree/master/kloppy/domain/services/state_builder/"
    click Trans "https://github.com/pysport/kloppy/tree/master/kloppy/domain/services/transformers/"

    %% Click Events for CLI & Utilities
    click CLI "https://github.com/pysport/kloppy/blob/master/kloppy/cmdline.py"
    click Helpers "https://github.com/pysport/kloppy/blob/master/kloppy/helpers.py"
    click Config "https://github.com/pysport/kloppy/blob/master/kloppy/config.py"
```
