# freshoats/nfl_injury_analytics architecture

> Architecture diagram of the GitHub repository freshoats/nfl_injury_analytics, 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/freshoats/nfl_injury_analytics
- Repository: https://github.com/freshoats/nfl_injury_analytics

## Overview

##### Project Type and Purpose
- This is a full-stack data analytics & machine-learning application, built in Python, that ingests NFL injury and punt datasets, cleans and stores them in PostgreSQL, performs exploratory analysis and model training (Random Forests, Neural Networks, PCA + K-Means), produces visualizations (Matplotlib, Tableau) and exposes an interactive web interface via Flask.

##### File-Structure Analysis
- Top-level scripts:
- app.py / app - Copy.py – Flask web server entry points
- scraping.py, Web_Scraper.ipynb, Injury_Scraper.ipynb – data retrieval
- requirements*.txt – Python dependencies
- Data folders:
- SQL/ – DDL scripts (ERDs, schema) for PostgreSQL
- Exploratory_Analysis/, Machine_Learning_Files/, Preliminary_Models/, Proof_of_Concept/, Post_Analysis/ – Jupyter notebooks and Python modules for EDA, model prototyping, post-processing
- Web UI assets:
- templates/ – HTML pages (index, algorithm, stats, report, etc.)
- static/ – CSS, images
- Artefacts: result CSVs, Tableau workbook (.twbx)
- Configuration: .gitignore, README.md

##### README Insights
- Data sources: two Kaggle competitions (Injury, Punt)
- Database: PostgreSQL with two ERDs (Injury_DB, PuntAnalytics_DB), ingested via SQLAlchemy (some CSV fallbacks for very large tables)
- Pipeline:
- ETL/Data Cleaning functions (InjuryCleaningFunctions.py, Punt_Cleaner.py, etc.)
- Exploratory Data Analysis (notebooks)
- Machine Learning (supervised & unsupervised)
- Post-analysis & visualizations (Tabl﻿eau, Matplotlib)
- Web app stitches static dashboards, ML results, narrative pages

a. Main Components
- Data Sources:
- Kaggle CSVs, tracking data (local CSVs), external web scrapes
- ETL Layer:
- Python scripts & modules (scraping.py, Injury_Scraper.ipynb, cleaning modules)
- SQLAlchemy connectors
- Database: PostgreSQL server (two schemas: injury_analytics, punt_analytics)
- Processing & ML Layer:
- Jupyter notebooks & Python modules under Machine_Learning_Files, Preliminary_Models, Post_Analysis
- Scikit-Learn (RandomForest, PCA, K-Means), Keras/TensorFlow (Neural Networks)
- Result artefacts: CSVs, SQL tables (Random_Forest_Outputs, Neural_Network_Outputs, Concussion_Analysis)
- Visualization Layer:
- Tableau Public dashboards (embedded via iFrames/JS)
- Python/Matplotlib notebooks for static plots
- Web Application (Flask):
- app.py routes → templates/ rendering with data pulls from PostgreSQL (SQLAlchemy) and embedded Tableau content
- static/ for CSS and images
- External Services: Render.com (hosting), PostgreSQL cloud, Tableau Public

b. Relationships & Data Flow
- Database ↔ Processing/ML Layer (reads base tables, writes result tables)
- ML Layer → Visualization Layer (publishes static CSVs, notebooks, Tableau extracts)
- Web App (Flask) → Database (via SQLAlchemy) and → Visualization Layer (embeds dashboards) → Browser UI

c. Architectural Patterns & Principles
- Layered (n-tier) architecture: Data Layer, Business/Analytics Layer, Presentation Layer
- Modular design: separate notebooks/scripts for cleaning, EDA, modeling, post-analysis
- Reuse of cleaning functions across pipelines (InjuryCleaningFunctions.py reused in ML & viz)
- Separation of concerns: web UI logic (Flask) vs. analytics (Jupyter/ML scripts)

d. Key Technologies & Frameworks
- Python 3.x, Flask, Jinja2 (templates)
- Pandas, NumPy for data manipulation
- SQLAlchemy for DB ORM
- PostgreSQL for persistent storage
- Scikit-Learn, imbalanced-learn, Keras/TensorFlow for ML
- Jupyter Notebooks for prototyping
- Tableau for interactive dashboards
- HTML, CSS, JavaScript for front-end
- Render.com (or similar) for deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    subgraph "External Sources"
        DS1["Kaggle CSVs<br>Concussion_Data.csv"]:::external
        DS2["Web Scrapes<br>Web_Scraper.ipynb"]:::external
        DS3["Injury Scraper<br>Injury_Scraper.ipynb"]:::external
        DS4["scraping.py"]:::processing
    end

    %% ETL Layer
    subgraph "ETL Layer" 
        EC1["InjuryCleaningFunctions.py"]:::processing
        EC2["Punt_Cleaner.py"]:::processing
        EC3["Punt_SQL_Cleaner.py"]:::processing
        EC4["MergeCleaner.py"]:::processing
        EC5["NGS_Cleaner.py"]:::processing
        EC6["PostAnalysisCleaningFunctions.py"]:::processing
        EC7["ConcussionCleaningFunctions.py"]:::processing
        EC8["NGS_Cleaner (Post)"]:::processing
    end

    %% Database Layer
    subgraph "Database (PostgreSQL)" 
        DB1["injury_analytics_schema.sql"]:::db
        DB2["punt_schema.sql"]:::db
        ERD1["injury_analytics_erd.txt"]:::db
        ERD2["punt_schema_erd.txt"]:::db
        ERD3["FF_ERD.sql"]:::db
        ERD4["Punt_ERD.sql"]:::db
        ERD5["Punt_File_Merger.sql"]:::db
    end

    %% ML & Processing Layer
    subgraph "Machine Learning Layer"
        ML1["Injury_Supervised_Random_Forest.ipynb"]:::processing
        ML2["Injury_Supervised_Neural_Network.ipynb"]:::processing
        ML3["Concussion_Analysis.ipynb"]:::processing
        ML4["Preliminary_Injury_Supervised_Learning.ipynb"]:::processing
        ML5["Preliminary_Injury_Unsupervised_Learning.ipynb"]:::processing
        ML6["RandomForest_Results.csv"]:::processing
        ML7["NeuralNetwork_Results.csv"]:::processing
        PM1["Preliminary_Injury_ML.ipynb"]:::processing
        PM2["Supervised_Injury_Prediction.ipynb"]:::processing
        PM3["Supervised_Injury_Severity.ipynb"]:::processing
        PM4["Supervised_Models.ipynb"]:::processing
        PM5["Supervised_Undersampling_Injury.ipynb"]:::processing
    end

    %% Post-Analysis & Visualization
    subgraph "Post-Analysis & Visualization"
        PA1["Post_Analysis_Visualizations.ipynb"]:::presentation
        PA2["Post_Analysis_Vis_Injury_Tracking.ipynb"]:::presentation
        PA3["Post_Analysis_Concussion.ipynb"]:::presentation
        PA4["vis_concussions.csv"]:::presentation
        PA5["NFL Injury Data.twbx"]:::presentation
        MAT["Matplotlib Charts"]:::presentation
        TAB["Tableau Dashboards"]:::presentation
    end

    %% Web Application
    subgraph "Web Application (Flask)"
        WEB1["app.py"]:::presentation
        WEB2["app - Copy.py"]:::presentation
        TMP["templates/"]:::presentation
        STA["static/"]:::presentation
    end

    %% Deployment & External Services
    subgraph "Deployment & Services"
        REND["Render.com"]:::external
        TABPUB["Tableau Public"]:::external
    end

    %% Data Flow
    DS1 --> DS4
    DS2 --> DS4
    DS3 --> DS4
    DS4 --> EC1
    DS4 --> EC2
    DS4 --> EC3
    EC1 --> DB1
    EC2 --> DB2
    EC3 --> DB2
    EC4 --> DB1
    EC5 --> DB1
    EC6 --> DB1
    EC7 --> DB1
    EC8 --> DB1
    DB1 <--> ML1
    DB1 <--> ML2
    DB1 <--> ML4
    DB1 <--> ML5
    ML1 --> ML6
    ML2 --> ML7
    ML3 --> PA3
    ML6 --> PA1
    ML7 --> PA1
    PM1 --> ML6
    PM2 --> ML6
    PM3 --> ML6
    PM4 --> ML6
    PM5 --> ML6
    PA1 --> MAT
    PA2 --> MAT
    PA3 --> MAT
    PA4 --> MAT
    PA5 --> TAB
    DB1 --> WEB1
    DB2 --> WEB1
    MAT --> WEB1
    TAB --> WEB1
    WEB1 --> TMP
    WEB1 --> STA
    REND --> WEB1
    TABPUB --> TAB

    %% Click Events - Data Sources
    click DS1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Exploratory_Analysis/Concussion_Data.csv"
    click DS2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Web_Scraper.ipynb"
    click DS3 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Injury_Scraper.ipynb"
    click DS4 "https://github.com/freshoats/nfl_injury_analytics/blob/main/scraping.py"

    %% Click Events - ETL Layer
    click EC1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/InjuryCleaningFunctions.py"
    click EC2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Punt_Cleaner.py"
    click EC3 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Punt_SQL_Cleaner.py"
    click EC4 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/MergeCleaner.py"
    click EC5 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/NGS_Cleaner.py"
    click EC6 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/PostAnalysisCleaningFunctions.py"
    click EC7 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/ConcussionCleaningFunctions.py"
    click EC8 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/NGS_Cleaner.py"

    %% Click Events - Database
    click DB1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/injury_analytics_schema.sql"
    click DB2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/punt_schema.sql"
    click ERD1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/injury_analytics_erd.txt"
    click ERD2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/punt_schema_erd.txt"
    click ERD3 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/FF_ERD.sql"
    click ERD4 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/Punt_ERD.sql"
    click ERD5 "https://github.com/freshoats/nfl_injury_analytics/blob/main/SQL/Punt_File_Merger.sql"

    %% Click Events - ML Layer
    click ML1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Injury_Supervised_Random_Forest.ipynb"
    click ML2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Injury_Supervised_Neural_Network.ipynb"
    click ML3 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Concussion_Analysis.ipynb"
    click ML4 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Preliminary_Injury_Supervised_Learning.ipynb"
    click ML5 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/Preliminary_Injury_Unsupervised_Learning.ipynb"
    click ML6 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/RandomForest_Results.csv"
    click ML7 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Machine_Learning_Files/NeuralNetwork_Results.csv"
    click PM1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Preliminary_Models/Preliminary_Injury_ML.ipynb"
    click PM2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Preliminary_Models/Supervised_Injury_Prediction.ipynb"
    click PM3 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Preliminary_Models/Supervised_Injury_Severity.ipynb"
    click PM4 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Preliminary_Models/Supervised_Models.ipynb"
    click PM5 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Preliminary_Models/Supervised_Undersampling_Injury.ipynb"

    %% Click Events - Post Analysis & Visualization
    click PA1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/Post_Analysis_Visualizations.ipynb"
    click PA2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/Post_Analysis_Vis_Injury_Tracking.ipynb"
    click PA3 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/Post_Analysis_Concussion.ipynb"
    click PA4 "https://github.com/freshoats/nfl_injury_analytics/blob/main/Post_Analysis/vis_concussions.csv"
    click PA5 "https://github.com/freshoats/nfl_injury_analytics/blob/main/NFL Injury Data.twbx"

    %% Click Events - Web Application
    click WEB1 "https://github.com/freshoats/nfl_injury_analytics/blob/main/app.py"
    click WEB2 "https://github.com/freshoats/nfl_injury_analytics/blob/main/app - Copy.py"
    click TMP "https://github.com/freshoats/nfl_injury_analytics/tree/main/templates/"
    click STA "https://github.com/freshoats/nfl_injury_analytics/tree/main/static/"

    %% Styles
    classDef db fill:#blue,stroke:#000,color:#fff;
    classDef processing fill:#aaffaa,stroke:#000;
    classDef presentation fill:#ffcc99,stroke:#000;
    classDef external fill:#dddddd,stroke:#000;
```
