# scodive/matchpredict architecture

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

- Interactive diagram: https://gitdiagram.com/scodive/matchpredict
- Repository: https://github.com/scodive/matchpredict

## Overview

##### Project Type and Purpose
- This is a predictive analytics tool for football (soccer) matches. It gathers historical data, processes and calculates key performance indicators (features), and applies statistical prediction models (using SciPy’s Poisson distribution and optional Scikit-learn models) to forecast match outcomes and recommend bets.
- The system supports both command-line usage and a web-based interactive interface (see “app.py”, “index.html”, “js/” folder).

##### Main Components
a. Data Ingestion & Collection:
- Modules: data_collection.py, collect_league_data.py
- Data Sources: CSV/JSON files in the data/ directory (including raw match and team data, odds data, and pre-processed features).
- Function: Retrieve historical match data from APIs or local files and cache/store them.

b. Data Processing & Feature Engineering:
- Modules: data_processing.py, feature_engineering.py, convert_csv_to_json.py
- Data Flow: Raw CSV/JSON data → Feature extraction & transformation → Derived datasets for predictions.
- Use of libraries like Pandas and NumPy.

c. Prediction Engine:
- Prediction Scripts: match.py, parlay_predictor.py, models.py, match_predictor.py (if applicable from the sample structure in README).
- A component for odds analysis and value bets calculation.

d. Web/API Interface:
- Files: app.py (Flask-based API server), index.html, js/ (JavaScript files) and style.css.
- Function: Provides an interactive front end for users to input match parameters and view predictions.
- Deployment instructions with Gunicorn and Nginx (as detailed in README).

e. Configuration & Utility Services:
- Files: config.py (for configuration settings), __pycache__, and next.config.js (suggesting potential integration with Next.js for frontend, or configuration for deployment).
- Purpose: Manage settings for data sources, thresholds, and model configuration.

##### Relationships and Interactions
- Data flows from the “data/” directory (and external APIs) into the Data Processing module.
- The Feature Engineering layer transforms and cleans data which is then fed into the Prediction Engine.
- The Prediction Engine (executed via command-line scripts like match.py or parlay_predictor.py) provides outputs that are either rendered on a web interface (via app.py and static files like index.html, js/app.js) or returned as JSON responses for API calls.
- The configuration layer (config.py) provides global settings, and deployment scripts (e.g., Dockerfile, next.config.js, and deployment instructions in the README) orchestrate the environment.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project clearly separates data collection, data processing, prediction logic, and user interaction into distinct scripts and modules.
- Modularity & Reusability: Each script (or module) is responsible for a specific function, making it easier to maintain and upgrade (for instance, feature engineering is separated from prediction logic).
- Scalability & Deployment: The use of Docker, Flask, and Gunicorn indicates a design that can be scaled for production deployments. The static assets (HTML/CSS/JS) are kept separate from the backend logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        DS("Data Sources"):::data
    end

    %% Data Collection & Processing
    subgraph "Data Collection & Processing"
        DCC("Data Collection"):::data
        DProcessing("Data Processing"):::data
        FE("Feature Engineering"):::data
        C2J("CSV to JSON Converter"):::data
        PD("Processed Data"):::data
    end

    %% Prediction Engine
    subgraph "Prediction Engine"
        MP("Match Prediction"):::backend
        PP("Parlay Predictor"):::backend
        Models("Models"):::backend
    end

    %% Web/API Interface
    subgraph "Web/API Interface"
        API("API Server"):::frontend
        Index("Web Interface"):::frontend
        JS("Javascript Assets"):::frontend
        Style("Styles"):::frontend
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        Config("Configuration"):::config
        Next("Next Config"):::config
    end

    %% Data Flow
    DS --> DCC
    DCC --> DProcessing
    DProcessing --> FE
    FE --> C2J
    C2J --> PD
    PD --> MP
    PD --> PP
    PD --> Models
    MP --> API
    PP --> API
    Models --> API
    API --> Index
    API --> JS
    API --> Style
    Config -.-> API
    Next -.-> Index

    %% Click Events
    click DS "https://github.com/scodive/matchpredict/tree/main/data/"
    click DCC "https://github.com/scodive/matchpredict/blob/main/data_collection.py"
    click DProcessing "https://github.com/scodive/matchpredict/blob/main/data_processing.py"
    click FE "https://github.com/scodive/matchpredict/blob/main/feature_engineering.py"
    click C2J "https://github.com/scodive/matchpredict/blob/main/convert_csv_to_json.py"
    click MP "https://github.com/scodive/matchpredict/blob/main/match.py"
    click PP "https://github.com/scodive/matchpredict/blob/main/parlay_predictor.py"
    click Models "https://github.com/scodive/matchpredict/blob/main/models.py"
    click API "https://github.com/scodive/matchpredict/blob/main/app.py"
    click Index "https://github.com/scodive/matchpredict/blob/main/index.html"
    click JS "https://github.com/scodive/matchpredict/tree/main/js/"
    click Style "https://github.com/scodive/matchpredict/blob/main/style.css"
    click Config "https://github.com/scodive/matchpredict/blob/main/config.py"
    click Next "https://github.com/scodive/matchpredict/blob/main/next.config.js"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef frontend fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
