# donmichaell/euroleague_api architecture

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

- Interactive diagram: https://gitdiagram.com/donmichaell/euroleague_api
- Repository: https://github.com/donmichaell/euroleague_api

## Overview

##### Main Components
- API Client Library: The core of the project is contained in the “src/euroleague_api” directory. Each module (e.g., EuroLeagueData.py, game_stats.py, shot_data.py, etc.) represents a distinct API endpoint or data category.
- Documentation & Examples: The “docs” and “site” directories provide HTML-rendered documentation of the modules. The “notebooks” directory includes example notebooks for usage.
- Developer Tools: You have CI/CD configuration files (.github/workflows) and static analysis/setup files (pylintrc, mypy.ini, setup.cfg, pyproject.toml, requirements.txt, etc.) which support continuous integration, code quality, and packaging related aspects.
- External API: Represent the actual Euroleague endpoints as an external component (e.g. Swagger-based endpoints, blog-sourced endpoints).

##### Relationships and Interactions
- User/Consumer → API Client Library: Users install the package (via pip) and build their applications on top of it.
- API Client Library modules internally call one or more HTTP endpoints to fetch data. For example, ShotData in shot_data.py retrieves shot data when invoking methods.
- The modules rely on common utility functions (from utils.py) that help with common aspects (parsing, formatting, etc.).
- Documentation is auto-generated from the source code and is provided externally through the “site/” folder.

##### Architectural Patterns & Design Principles
- Layered Approach: At the base, you have the HTTP communication layer (connection to external endpoints) wrapped by individual modules that represent domain-specific data.
- Modularity: Each file/module is responsible for a specific aspect of the API (e.g., shot data, standings, play-by-play) making it easier to extend the API with additional endpoints.
- Separation of Concerns: Documentation, application logic (the Python package), and testing/examples (notebooks) are clearly separated.
- Extensibility: The design allows for additional endpoints or modules to be added as new files following the same structure.

##### Relevant Technologies & Frameworks
- Python (with emphasis on standard library HTTP client and optionally libraries like requests)
- Software quality tools (pre-commit, pylint, mypy)
- CI/CD environment provided by GitHub Actions (found in .github/workflows)

##### Elements
- Clearly Labeled Components:
- “User/Client Application” – that imports/uses the package.
- “Euroleague API Package” – with contained modules for EuroLeagueData, game_stats, player_stats, team_stats, shot_data, play_by_play_data, boxscore_data, and utils.
- “External Euroleague API Endpoints” – representing the live API.
- “Documentation/Examples” – highlighting the notebooks and generated HTML docs.
- “CI/CD and Quality Tools” – encapsulating GitHub workflows and static configurations.
- From the “User/Client Application” to individual API modules to show how methods (e.g., get_game_shot_data) are invoked.
- From API modules to the “External Euroleague API Endpoints” indicating data requests/responses.
- Visual Differentiation: Use:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    User["User/Client Application"]:::user

    %% Core Package containing modules and utilities
    subgraph "Euroleague API Package"
        APICore["Euroleague API Package"]:::internal
        Utilities["Utility Functions"]:::internal
        subgraph "Endpoint Modules"
            EuroLeagueData["EuroLeagueData Module"]:::internal
            GameStats["Game Stats Module"]:::internal
            ShotData["Shot Data Module"]:::internal
            PlayerStats["Player Stats Module"]:::internal
            TeamStats["Team Stats Module"]:::internal
            BoxscoreData["Boxscore Data Module"]:::internal
            PlayByPlay["Play-By-Play Data Module"]:::internal
            Standings["Standings Module"]:::internal
        end
    end

    %% External API Endpoints
    External["External Euroleague API Endpoints"]:::external

    %% Documentation and Examples
    subgraph "Supporting Documentation & Examples"
        Docs["Documentation (Source)"]:::docs
        Notebooks["Examples (Notebooks)"]:::docs
    end

    %% CI/CD & Quality Tools
    CICD["CI/CD & Quality Tools"]:::ci

    %% Data Flow / Interactions
    User -->|"uses"| APICore
    APICore -->|"documented_by"| Docs
    Notebooks -->|"example_usage"| APICore
    CICD -->|"runs_tests"| APICore

    %% Modules calling External API and using Utilities
    EuroLeagueData -->|"HTTP"| External
    GameStats -->|"HTTP"| External
    ShotData -->|"HTTP"| External
    PlayerStats -->|"HTTP"| External
    TeamStats -->|"HTTP"| External
    BoxscoreData -->|"HTTP"| External
    PlayByPlay -->|"HTTP"| External
    Standings -->|"HTTP"| External

    EuroLeagueData -->|"uses"| Utilities
    GameStats -->|"uses"| Utilities
    ShotData -->|"uses"| Utilities
    PlayerStats -->|"uses"| Utilities
    TeamStats -->|"uses"| Utilities
    BoxscoreData -->|"uses"| Utilities
    PlayByPlay -->|"uses"| Utilities
    Standings -->|"uses"| Utilities

    %% Click Events for API Client Library and Modules
    click APICore "https://github.com/donmichaell/euroleague_api/tree/main/src/euroleague_api"
    click EuroLeagueData "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/EuroLeagueData.py"
    click GameStats "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/game_stats.py"
    click ShotData "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/shot_data.py"
    click PlayerStats "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/player_stats.py"
    click TeamStats "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/team_stats.py"
    click BoxscoreData "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/boxscore_data.py"
    click PlayByPlay "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/play_by_play_data.py"
    click Standings "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/standings.py"
    click Utilities "https://github.com/donmichaell/euroleague_api/blob/main/src/euroleague_api/utils.py"
    click Docs "https://github.com/donmichaell/euroleague_api/tree/main/docs/euroleague_api"
    click Docs "https://github.com/donmichaell/euroleague_api/tree/main/site/euroleague_api"
    click Notebooks "https://github.com/donmichaell/euroleague_api/tree/main/notebooks"
    click CICD "https://github.com/donmichaell/euroleague_api/tree/main/.github/workflows"

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef docs fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef ci fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
