# areebfazli/football_prediction architecture

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

- Interactive diagram: https://gitdiagram.com/areebfazli/football_prediction
- Repository: https://github.com/areebfazli/football_prediction

## Overview

##### Project type and purpose
- This is a lightweight machine‐learning prediction service, implemented in Python, that provides REST API endpoints (via app.py) to predict goals and assists using two linear models and two deep‐learning models.
- It also contains Jupyter notebooks under models/ for offline training and experimentation.

##### File structure
- Top level
– .devcontainer/ : developer environment settings (VS Code Remote‐Container)
– app.py : main Flask/FastAPI (or similar) entry point for serving predictions
– requirements.txt : Python dependencies (e.g., Flask/FastAPI, scikit-learn, tensorflow/keras)
- models/
– app.py : utility module to load models, scalers, and run inference
– fnn_*.ipynb, lr_*.ipynb : Jupyter notebooks for training various models
– saved_model/ : serialized artifacts for each model variant
· col_order.pkl, scaler_X.pkl, scaler_y.pkl, weights.npy, fnn_model.keras
- No external database is pictured—models and preprocessing objects are stored on disk.

##### README
- Confirms exactly four predictive models (2 linear, 2 DNN) for goals and assists.
- No mention of persistence layers beyond file storage or external APIs.

##### Main components and their interactions
a. Client Layer
– HTTP client (e.g., CURL, frontend UI, Postman) sends prediction requests
b. API/Inference Service
– app.py (Flask/FastAPI)
- Receives request → parses input JSON features
- Calls model‐loader utilities in models/app.py
c. Preprocessing & Model Loader
– models/app.py
- Loads col_order and scaler_X, scaler_y from saved_model/*
- Applies feature ordering and scaling
d. Model Inference
– Four model artifacts (linear_gradient_descent, linear_normal_equation, fnn_basic, fnn_tuned)
- Each implements a predict() interface
- Output predictions of goals and assists
e. Response Layer
– Inference service assembles model outputs and returns JSON to client
– Jupyter notebooks under models/
- Read raw data (e.g., goals_predict.csv) → train/test splits → fit models → serialize artifacts to models/saved_model

##### Architectural patterns & design principles
- Separation of concerns:
– API layer vs. preprocessing vs. model definitions vs. training notebooks
- Stateless inference service:
– All model state is loaded on startup or per‐request from file system
- Modular model artifacts:
– Each algorithm variant lives in its own subfolder under saved_model/
- Reproducible dev environment via .devcontainer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["HTTP Client\n(CURL/Postman/UI)"]:::external
    end

    %% Online Inference Workflow
    subgraph "Online Inference" 
        API["API Service (app.py)\nPython, Flask/FastAPI"]:::online
        Loader["Preprocessing & Model Loader\n(models/app.py)\nscikit-learn, TensorFlow"]:::online
    end

    %% Model Store
    subgraph "Model Store (File System)" 
        MD1["Linear Model\nGradient Descent"]:::storage
        MD2["Linear Model\nNormal Equation"]:::storage
        MD3["Deep Learning Model\nBasic FNN"]:::storage
        MD4["Deep Learning Model\nTuned FNN"]:::storage
    end

    %% Offline Training Pipeline
    subgraph "Offline Training Pipeline"
        CSV["Sample Data\n(goals_predict.csv)"]:::offline
        N1["Notebook: Linear – Gradient Descent"]:::offline
        N2["Notebook: Linear – Normal Equation"]:::offline
        N3["Notebook: FNN – Basic"]:::offline
        N4["Notebook: FNN – Tuned"]:::offline
    end

    %% Infrastructure
    Devcontainer["Dev Container\n(.devcontainer)"]:::infra

    %% Connections - Online
    Client -->|"HTTP Request"| API
    API -->|"invoke load and preprocess"| Loader
    Loader -->|"loads artifacts"| MD1
    Loader --> MD2
    Loader --> MD3
    Loader --> MD4
    MD1 -->|"predictions"| API
    MD2 --> API
    MD3 --> API
    MD4 --> API
    API -->|"HTTP Response"| Client

    %% Connections - Offline
    CSV --> N1
    CSV --> N2
    CSV --> N3
    CSV --> N4
    N1 -->|"serialize artifacts"| MD1
    N2 --> MD2
    N3 --> MD3
    N4 --> MD4

    %% Devcontainer
    Devcontainer -.-> API
    Devcontainer -.-> Loader
    Devcontainer -.-> N1
    Devcontainer -.-> N2
    Devcontainer -.-> N3
    Devcontainer -.-> N4

    %% Click Events
    click API "https://github.com/areebfazli/football_prediction/blob/main/app.py"
    click Loader "https://github.com/areebfazli/football_prediction/blob/main/models/app.py"
    click MD1 "https://github.com/areebfazli/football_prediction/tree/main/models/saved_model/gradient_descent/"
    click MD2 "https://github.com/areebfazli/football_prediction/tree/main/models/saved_model/normal_equation/"
    click MD3 "https://github.com/areebfazli/football_prediction/tree/main/models/saved_model/fnn_basic/"
    click MD4 "https://github.com/areebfazli/football_prediction/tree/main/models/saved_model/fnn_tuned/"
    click N1 "https://github.com/areebfazli/football_prediction/blob/main/models/lr_gradient_descent.ipynb"
    click N2 "https://github.com/areebfazli/football_prediction/blob/main/models/lr_normal_equation.ipynb"
    click N3 "https://github.com/areebfazli/football_prediction/blob/main/models/fnn_basic.ipynb"
    click N4 "https://github.com/areebfazli/football_prediction/blob/main/models/fnn_tuned.ipynb"
    click CSV "https://github.com/areebfazli/football_prediction/blob/main/models/goals_predict.csv"
    click Devcontainer "https://github.com/areebfazli/football_prediction/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef online fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef offline fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20;
    classDef storage fill:#CFD8DC,stroke:#607D8B,color:#263238;
    classDef external fill:#FFF3E0,stroke:#FF9800,color:#E65100;
    classDef infra fill:#ECEFF1,stroke:#78909C,color:#546E7A;
```
