# federicorabanos/lanusstats architecture

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

- Interactive diagram: https://gitdiagram.com/federicorabanos/lanusstats
- Repository: https://github.com/federicorabanos/lanusstats

## Overview

##### Project Type and Purpose
- This is a domain-specific Python library (SDK) named “LanusStats” for scraping football data and producing quick visualizations.
- It provides a unified API over five data sources (FBRef, FotMob, SofaScore, 365Scores, Transfermarkt) plus plotting utilities via a visualizations module.
- Users install via pip and call high-level functions or instantiate scraper classes to get pandas DataFrames or charts.

##### File-Structure Analysis
- Top level
- .github/workflows/publish-package.yml – CI/CD pipeline to run tests/build and publish to PyPI.
- setup.py – package metadata, dependencies and entry points.
- README.md – user documentation and examples.
- LanusStats/ package
- config.py – constants, URL templates, selectors.
- datafactory.py – factory that, given a page name, returns the right scraper instance.
- exceptions.py – custom exception types for error handling across scrapers.
- functions.py – generic helper functions (e.g., get_available_pages, get_available_leagues).
- fbref.py, fotmob.py, sofascore.py, threesixfivescores.py, transfermarkt.py – one scraper class per data source, each implementing a common interface (request → parse → DataFrame).
- visualizations.py – plotting routines that wrap scraping calls and chart with Matplotlib/MPLSoccer.

##### Key README Insights
- Each scraper class exposes methods like get_teams_season_stats, get_player_season_stats, get_match_shotmap, etc.
- The library returns pandas DataFrames (optionally saved to CSV/XLSX) or Matplotlib figures (optionally saved).
- There’s a clear layering: user API → datafactory/functions → scraper classes → HTTP requests → HTML parsing → DataFrame → optional visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client Application"]:::external

    %% LanusStats Package
    subgraph "LanusStats Package"
        subgraph "API Layer"
            API["LanusStats Public API\n(__init__.py)"]:::internal
            Functions["Helper Functions\n(functions.py)"]:::internal
        end
        subgraph "Factory & Core"
            DataFactory["DataFactory\n(datafactory.py)"]:::internal
            Config["Config & Selectors\n(config.py)"]:::internal
            Exceptions["Exceptions\n(exceptions.py)"]:::internal
        end
        subgraph "Scraper Modules"
            FBRef["Fbref Scraper\n(fbref.py)"]:::internal
            FotMob["FotMob Scraper\n(fotmob.py)"]:::internal
            Sofa["SofaScore Scraper\n(sofascore.py)"]:::internal
            Three["365Scores Scraper\n(threesixfivescores.py)"]:::internal
            Transfer["Transfermarkt Scraper\n(transfermarkt.py)"]:::internal
        end
        subgraph "Visualization"
            Viz["Visualizations\n(visualizations.py)"]:::internal
        end
    end

    %% External Data Sources
    subgraph "External Data Sources"
        E1["FBRef"]:::external
        E2["FotMob"]:::external
        E3["SofaScore"]:::external
        E4["365Scores"]:::external
        E5["Transfermarkt"]:::external
    end

    %% Tooling & Publishing
    subgraph "Tooling & Publishing"
        CI["CI/CD Pipeline\n(.github/workflows/publish-package.yml)"]:::tooling
        Packaging["Packaging & Metadata\n(setup.py)"]:::tooling
        Docs["Documentation & Examples\n(README.md)"]:::tooling
        PYPI["PyPI Registry"]:::external
    end

    %% Data Flows
    Client -->|calls API| API
    API -->|uses| Functions
    API -->|delegates| DataFactory
    API -->|can instantiate| FBRef
    API -->|can instantiate| FotMob
    API -->|can instantiate| Sofa
    API -->|can instantiate| Three
    API -->|can instantiate| Transfer

    DataFactory -->|selects scraper| FBRef
    DataFactory -->|selects scraper| FotMob
    DataFactory -->|selects scraper| Sofa
    DataFactory -->|selects scraper| Three
    DataFactory -->|selects scraper| Transfer

    Config -->|provides URLs/selectors| FBRef
    Config -->|provides URLs/selectors| FotMob
    Config -->|provides URLs/selectors| Sofa
    Config -->|provides URLs/selectors| Three
    Config -->|provides URLs/selectors| Transfer

    FBRef -->|HTTP request/response| E1
    FotMob -->|HTTP request/response| E2
    Sofa -->|HTTP request/response| E3
    Three -->|HTTP request/response| E4
    Transfer -->|HTTP request/response| E5

    FBRef -->|DataFrame| Viz
    FotMob -->|DataFrame| Viz
    Sofa -->|DataFrame| Viz
    Three -->|DataFrame| Viz
    Transfer -->|DataFrame| Viz

    Viz -->|chart/figure| Client

    Exceptions -->|error flow| API

    Client -->|reads| Docs
    CI -->|build & test| Packaging
    CI -->|publishes| PYPI
    Packaging -->|publishes| PYPI

    %% Click Events
    click API "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/__init__.py"
    click Functions "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/functions.py"
    click DataFactory "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/datafactory.py"
    click Config "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/config.py"
    click Exceptions "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/exceptions.py"
    click FBRef "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/fbref.py"
    click FotMob "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/fotmob.py"
    click Sofa "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/sofascore.py"
    click Three "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/threesixfivescores.py"
    click Transfer "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/transfermarkt.py"
    click Viz "https://github.com/federicorabanos/lanusstats/blob/main/LanusStats/visualizations.py"
    click CI "https://github.com/federicorabanos/lanusstats/blob/main/.github/workflows/publish-package.yml"
    click Packaging "https://github.com/federicorabanos/lanusstats/blob/main/setup.py"
    click Docs "https://github.com/federicorabanos/lanusstats/blob/main/README.md"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#2980B9
    classDef external fill:#D5F5E3,stroke:#27AE60
    classDef tooling fill:#FCF3CF,stroke:#F1C40F
```
