# jakeharveyy/nrl-tipping-app-backend architecture

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

- Interactive diagram: https://gitdiagram.com/jakeharveyy/nrl-tipping-app-backend
- Repository: https://github.com/jakeharveyy/nrl-tipping-app-backend

## Overview

##### Project type and purpose
- This is a Flask-based backend API for an NRL tipping application. It provides REST endpoints, background jobs (scraping, data updates, AI predictions), server-sent events for real-time updates, and a CLI for maintenance tasks. The frontend (React) is in a separate repo.

##### File structure
- Top level:
- run.py, .flaskenv, Procfile, docker-compose.yml – entry points and deployment
- app/ – the main application package
- migrations/ – Alembic database migrations
- app/ layout:
- app/__init__.py & config.py – app factory and environment setup
- app/api/ – REST routes and settlement logic
- app/services/ – business-logic services (betting, scraping, AI orchestration)
- app/ai_models/ – trained ML artifacts, feature engineering, prediction pipeline
- app/models.py – SQLAlchemy model definitions
- app/sse_events.py – server-sent events for live updates
- app/utils/ – helper functions
- Scheduling & CLI: uses Flask-APScheduler for periodic scraping & prediction, and Flask CLI commands in run.py.

##### README for additional insights
- Technologies: Python 3.13, Flask, SQLAlchemy, MySQL/SQLite, Flask-RESTful, JWT, CORS, APScheduler, OAuth, Pandas/NumPy, scikit-learn, Beautiful Soup, Alembic.
- External integrations: NRL.com scraping, Google OAuth, frontend via CORS.
- Execution flow: user actions → REST API → services → database/AI → responses / SSE.

##### Detailed capture of architectural elements
- Break the backend into:
- HTTP API layer (Flask blueprints / routes)
- Service layer modules (app/services/*.py)
- Data persistence (models.py + migrations + MySQL)
- AI pipeline (app/ai_models/)
- Scheduler & CLI (Flask-APScheduler, run.py commands)
- Real-time updates (sse_events.py)
- External integrations:
- NRL scrapable data source
- Google OAuth
- Deployment context (Docker Compose, Heroku Procfile).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    FE["Frontend (React)"]:::external
    NRL["NRL.com API"]:::external
    GOOGLE["Google OAuth"]:::external
    CLIENTS["Clients (SSE subscribers)"]:::external

    %% Deployment & Environment
    subgraph "Deployment & Environment"
        FLASKENV[".flaskenv"]:::config
        PROCFILE["Procfile"]:::config
        DC["docker-compose.yml"]:::config
        REQ["requirements.txt"]:::config
        RUNTIME["runtime.txt"]:::config
    end

    %% Backend Entry Point & Config
    subgraph "Backend API Service"
        RUN["run.py"]:::api
        INIT["app/__init__.py"]:::api
        CONFIG["app/config.py"]:::api
    end

    %% HTTP API Layer
    subgraph "HTTP API Layer"
        APIINIT["app/api/__init__.py"]:::api
        ROUTES["app/api/routes.py"]:::api
        SETTLE["app/api/settlement.py"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        SSERVICE["app/services/odds_scraper_service.py"]:::service
        RSERVICE["app/services/results_scraper_service.py"]:::service
        HUPDATER["app/services/historical_data_updater.py"]:::service
        AISERVICE["app/services/ai_prediction_service.py"]:::service
        BSERVICE["app/services/betting_service.py"]:::service
        ROUND["app/services/round_service.py"]:::service
        SINIT["app/services/__init__.py"]:::service
    end

    %% Data Models & Persistence
    subgraph "Data Persistence"
        MODELS["app/models.py"]:::db
        subgraph "Alembic Migrations"
            MIG_ENV["migrations/env.py"]:::db
            MIG_INI["migrations/alembic.ini"]:::db
            MIG_VERS["migrations/versions/*.py"]:::db
        end
        DB["MySQL/SQLite DB"]:::db
    end

    %% AI Module
    subgraph "AI Module"
        MODEL1["app/ai_models/nrl_baseline_logistic_model.pkl"]:::ai
        MODEL2["app/ai_models/nrl_feature_scaler.pkl"]:::ai
        subgraph "AI Data"
            DATA1["app/ai_models/data/nrl_matches_final_model_ready.csv"]:::ai
            DATA2["app/ai_models/data/nrl_team_stats_final_complete.csv"]:::ai
        end
        subgraph "Prediction Pipeline"
            FE["app/ai_models/prediction/feature_engineering.py"]:::ai
            PREDUP["app/ai_models/prediction/predict_upcoming_matches.py"]:::ai
            PIPE["app/ai_models/prediction/prediction_pipeline.py"]:::ai
            PINIT["app/ai_models/prediction/__init__.py"]:::ai
        end
    end

    %% Real-time Updates
    SSE["app/sse_events.py"]:::service

    %% Utilities
    UTIL["app/utils/text_utils.py"]:::util

    %% Scheduler & CLI
    SCHED["Scheduler & CLI (Flask-APScheduler & CLI cmds)"]:::scheduler

    %% Connections
    FE -->|REST API calls| ROUTES
    FE -->|CORS| APIINIT
    ROUTES -->|calls| SSERVICE
    ROUTES -->|calls| RSERVICE
    ROUTES -->|calls| BSERVICE
    ROUTES -->|calls| ROUND
    ROUTES -->|auth via| GOOGLE
    ROUTES -->|login| GOOGLE
    ROUTES -->|issue JWT| ROUTES
    SSERVICE -->|store odds| DB
    RSERVICE -->|store results| DB
    HUPDATER -->|update history| DB
    AISERVICE -->|predict| PREDUP
    PREDUP -->|uses| FE & PIPE
    PIPE -->|aggregate| DB
    PREDUP -->|store predictions| DB
    ROUTES -->|query| DB
    MODELS -->|define schema| DB
    MIG_ENV -->|migrations| DB
    SCHED -->|periodic| SSERVICE
    SCHED -->|periodic| RSERVICE
    SCHED -->|periodic| HUPDATER
    SCHED -->|periodic| AISERVICE
    RUN -->|starts| SCHED
    RUN -->|registers| SCHED
    RUN -->|CLI commands| SCHED
    RUN -->|runs app| INIT
    INIT -->|configures| CONFIG
    INIT -->|registers blueprints| APIINIT
    APIINIT -->|includes routes| ROUTES & SETTLE
    ROUTES -->|settlement logic| SETTLE
    ROUTES -->|push updates| SSE
    CLIENTS -->|subscribe| SSE
    SSE -->|push events| CLIENTS
    RUN -->|loads env| FLASKENV

    FE -->|deployed via| DC
    RUN -->|deployed via| DC
    DC -->|includes| PROCFILE & REQ & RUNTIME

    NRL -->|scrape data| SSERVICE & RSERVICE

    UTIL -->|helper| SSERVICE & RSERVICE & AISERVICE

    %% Click Events
    click RUN "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/run.py"
    click FLASKENV "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/.flaskenv"
    click PROCFILE "https://github.com/jakeharveyy/nrl-tipping-app-backend/tree/main/Procfile"
    click DC "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/docker-compose.yml"
    click INIT "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/__init__.py"
    click CONFIG "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/config.py"
    click APIINIT "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/api/__init__.py"
    click ROUTES "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/api/routes.py"
    click SETTLE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/api/settlement.py"
    click SSERVICE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/odds_scraper_service.py"
    click RSERVICE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/results_scraper_service.py"
    click HUPDATER "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/historical_data_updater.py"
    click AISERVICE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/ai_prediction_service.py"
    click BSERVICE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/betting_service.py"
    click ROUND "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/round_service.py"
    click SINIT "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/services/__init__.py"
    click MODELS "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/models.py"
    click MIG_ENV "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/migrations/env.py"
    click MIG_INI "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/migrations/alembic.ini"
    click MIG_VERS "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/migrations/versions/*.py"
    click MODEL1 "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/nrl_baseline_logistic_model.pkl"
    click MODEL2 "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/nrl_feature_scaler.pkl"
    click DATA1 "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/data/nrl_matches_final_model_ready.csv"
    click DATA2 "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/data/nrl_team_stats_final_complete.csv"
    click FE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/prediction/feature_engineering.py"
    click PREDUP "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/prediction/predict_upcoming_matches.py"
    click PIPE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/prediction/prediction_pipeline.py"
    click PINIT "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/ai_models/prediction/__init__.py"
    click SSE "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/sse_events.py"
    click UTIL "https://github.com/jakeharveyy/nrl-tipping-app-backend/blob/main/app/utils/text_utils.py"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef service fill:#bfb,stroke:#333,stroke-width:1px
    classDef db fill:#fbf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef ai fill:#ffb,stroke:#333,stroke-width:1px
    classDef util fill:#ffd,stroke:#333,stroke-width:1px
    classDef scheduler fill:#fbc,stroke:#333,stroke-width:1px
```
