# mcekovic/tennis-crystal-ball architecture

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

- Interactive diagram: https://gitdiagram.com/mcekovic/tennis-crystal-ball
- Repository: https://github.com/mcekovic/tennis-crystal-ball

## Overview

##### Main Components
- Tennis Stats Web Application: This is the primary front-end and backend service built using Spring Boot. It handles MVC (controllers, views via Thymeleaf), REST endpoints, business logic, and caching (using the Caffeine library).
- Tennis Crystal Ball Module: This module focuses on the match prediction and tournament forecasting algorithms. It also contains various models (data objects, Elo calculations, forecasting, etc.) and is integrated into the overall business logic.
- Data Load Module: Implemented in Groovy, this module is responsible for importing tennis match data from external sources. It includes database scripts (SQL setup, migration, and data cleaning) and uses external tools (e.g., Selenium with Geckodriver and Headless Firefox) to scrape or fetch data.
- Database: PostgreSQL is used as the central data store. There are several SQL scripts for setting up tables, views, functions, migration steps, etc.
- External Services & Infrastructure: The project utilizes Docker for containerized builds (as seen in Dockerfiles), CI/CD pipelines (Travis CI, GitHub Actions, CodeQL analysis), and even a Let's Encrypt Certbot integration for SSL certificate management.
- Frontend Assets: The web UI provides various pages such as player profiles, GOAT lists, timelines, and prediction visualizations—all rendered by Thymeleaf and supported by static resources (CSS, JavaScript, images).

##### Relationships and Data Flows
- Web Users interact with the Tennis Stats Web Application via the browser. The application’s controllers (Spring MVC) receive HTTP requests and route them to service components.
- The Service Layer makes use of business logic from both Tennis Stats (e.g., ranking charts, performance analytics) and the Tennis Crystal Ball module (for predictions and Elo rating calculations).
- A Caching component (implemented with the Caffeine library) boosts performance by storing frequently accessed data.
- The Data Load Module, possibly spawned by the main application, fetches tennis match data from external repositories (like Jeff Sackmann’s tennis data) and web services (using Selenium, Geckodriver, and Headless Firefox) before staging and updating the database.
- Integration between the modules is also seen through scheduled jobs and REST endpoints (for instance, the match prediction engine is triggered as part of background jobs).

##### Architectural Patterns and Technologies
- MVC Pattern: Clearly separate controllers, service layers, and data access (repositories). This is evident in the tennis-stats module.
- Micro-modular Design: The existence of separate modules (crystal-ball, data-load, tennis-stats) implies a well-modularized code base where each module’s responsibilities are clearly defined.
- CI/CD Integration: Incorporate external build and testing infrastructure (Travis CI, GitHub Workflows). Although these are auxiliary, they may be depicted as external systems feeding into the build process.
- Docker & Containerization: Show Docker images (for example in the tennis-stats and crystal-ball modules) as part of the deployment process.
- External Integrations: Include highlights for external services such as Let's Encrypt for SSL and external data sources (Jeff Sackmann’s tennis repo and web scraping utilities).

- the Frontend/Web UI (Tennis Stats)
- Business Logic & Prediction (combining services from tennis-stats and crystal-ball)
- Data Load / ETL process
- Database (PostgreSQL)
- External integrations (SSL via Certbot; Docker containerization; CI/CD servers)
- User → Web Application (HTTP requests)
- Web Application ←→ Business Logic/Prediction modules (internal service calls and caching)
- Business Logic → Database (reads, writes, and migrations)
- Data Loader → Database (data ingestion) and Data Loader → External Data Source

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    User("User"):::external

    %% Frontend / Web UI Cluster
    subgraph "Frontend / Web UI"
        TStats("Tennis Stats Web Application (Spring Boot, Thymeleaf, Caffeine)"):::frontend
        TStatsCache("Caching & Business Logic (RegisterCaffeineCachesAspect)"):::frontend
    end

    %% Business Logic & Prediction Cluster
    subgraph "Business Logic & Prediction"
        TCrystal("Tennis Crystal Ball Module (Prediction Engine, Elo, Forecasting)"):::business
        CCBDScripts("Crystal Ball DB Scripts"):::business
    end

    %% Data Load / ETL Process Cluster
    subgraph "Data Load / ETL Process"
        DataLoad("Data Load Module (Groovy, Selenium, Web Scraping)"):::dataload
        DLDBScripts("Data Load DB Scripts"):::dataload
    end

    %% Database
    DB("PostgreSQL Database"):::database

    %% External Integrations Cluster
    subgraph "External Integrations"
        TennisDocker("Tennis Stats Docker"):::external
        CrystalDocker("Crystal Ball Docker"):::external
        GitHubWorkflows("GitHub Workflows"):::external
        TravisCI("Travis CI"):::external
        SSL("SSL Certbot (Let's Encrypt)"):::external
        ExternalData("External Data Sources"):::external
    end

    %% Data Flows and Relationships
    User -->|"HTTP_Request"| TStats
    TStats -->|"applyCachin"| TStatsCache
    TStats -->|"callsPrediction"| TCrystal
    TStats -->|"read/write"| DB
    TCrystal -->|"usesSQL"| CCBDScripts
    TCrystal -->|"read/write"| DB
    DataLoad -->|"usesDBScripts"| DLDBScripts
    DataLoad -->|"ingestsData"| DB
    DataLoad -->|"fetchesData"| ExternalData
    TStats -->|"triggersDataLoad"| DataLoad

    TennisDocker --> TStats
    CrystalDocker --> TCrystal
    GitHubWorkflows --> TennisDocker
    GitHubWorkflows --> CrystalDocker
    TravisCI --> TennisDocker
    TravisCI --> CrystalDocker
    SSL --> TStats

    %% Styling Classes
    classDef frontend fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef business fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef dataload fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef database fill:#ffe6cc,stroke:#ff9900,stroke-width:2px;
    classDef external fill:#e6e6e6,stroke:#666666,stroke-width:2px;

    %% Click Events
    click TStats "https://github.com/mcekovic/tennis-crystal-ball/tree/master/tennis-stats"
    click TStatsCache "https://github.com/mcekovic/tennis-crystal-ball/blob/master/tennis-stats/src/main/java/org/strangeforest/tcb/stats/spring/RegisterCaffeineCachesAspect.java"
    click TCrystal "https://github.com/mcekovic/tennis-crystal-ball/tree/master/crystal-ball"
    click CCBDScripts "https://github.com/mcekovic/tennis-crystal-ball/tree/master/crystal-ball/src/main/db"
    click DataLoad "https://github.com/mcekovic/tennis-crystal-ball/tree/master/data-load"
    click DLDBScripts "https://github.com/mcekovic/tennis-crystal-ball/tree/master/data-load/src/main/db"
    click TennisDocker "https://github.com/mcekovic/tennis-crystal-ball/tree/master/tennis-stats/Dockerfile"
    click CrystalDocker "https://github.com/mcekovic/tennis-crystal-ball/tree/master/crystal-ball/Dockerfile"
    click GitHubWorkflows "https://github.com/mcekovic/tennis-crystal-ball/tree/master/.github/workflows"
    click TravisCI "https://github.com/mcekovic/tennis-crystal-ball/blob/master/.travis.yml"
```
