# asim-shoaib/fantasypredictorserver architecture

> Architecture diagram of the GitHub repository asim-shoaib/fantasypredictorserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asim-shoaib/fantasypredictorserver
- Repository: https://github.com/asim-shoaib/fantasypredictorserver

## Overview

DraftGenius turns a selected PSL matchup into player profiles and three fantasy-team recommendations, with live genetic-algorithm progress delivered to the browser. Its main runtime path runs from the React match and results screens through Flask routes, profile construction, form/Elo scoring, and team optimization. A separate data-preparation workflow ingests Cricsheet matches and produces the Elo dataset used by the app. The README documents the SSE experience and major capabilities; some route-to-frontend and unsampled subsystem details are therefore shown only where documented, not inferred from names.

Main entry points: [`backend/data_cache.py`](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/data_cache.py) (Runtime data cache), [`backend/app.py`](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/app.py) (Flask application), [`backend/jobs/pipeline.py`](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/pipeline.py) (Match scoring pipeline), [`backend/services/player_service.py`](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/player_service.py) (Player profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Fantasy web app"]
  node_home["Match selection<br/>[Home.tsx]"]
  node_app["App routing<br/>[App.tsx]"]
  node_matchview["Match workspace<br/>[Match.tsx]"]
  node_results["Team results<br/>[Results.tsx]"]
  node_generatehook["Generation stream<br/>[useGenerate.ts]"]
  node_client["API client<br/>[client.ts]"]
  node_evolution["GA evolution view"]
end

subgraph group_api["Flask API"]
  node_apiapp["Flask application<br/>[app.py]"]
  node_playerroute["Player endpoints<br/>[players.py]"]
  node_teamroute["Team generation endpoints<br/>[teams.py]"]
  node_constraints["Constraint endpoints<br/>[constraints.py]"]
  node_roster["Roster controls<br/>[roster.py]"]
  node_matchroute["Franchise listing<br/>[match.py]"]
end

subgraph group_analytics["Player analytics"]
  node_cache[("Runtime data cache<br/>[data_cache.py]")]
  node_profiles["Player profiles<br/>[player_service.py]"]
  node_hmm["Form prediction<br/>[predictor.py]"]
  node_shortterm["Player HMM<br/>[short_term_hmm.py]"]
  node_generalhmm["General HMM<br/>[general_hmm.py]"]
  node_credit["Fantasy credits<br/>[credit_engine.py]"]
  node_elo["Elo ratings<br/>[elo_engine.py]"]
  node_features["Form features<br/>[form_features.py]"]
  node_profilesfetch["Headshot fetching<br/>[profile_fetcher.py]"]
end

subgraph group_optimizer["Team optimization"]
  node_generator["Genetic optimizer<br/>[team_generator.py]"]
end

subgraph group_pipeline["Data preparation"]
  node_pipeline["Match scoring pipeline<br/>[pipeline.py]"]
  node_loader["Match file loader<br/>[match_loader.py]"]
  node_parser["Match parser<br/>[match_parser.py]"]
  node_smartcache[("Parsed match cache<br/>[smart_cache.py]")]
  node_roles["Role resolution<br/>[role_resolver.py]"]
  node_scoring["Fantasy point scoring<br/>[scoring.py]"]
  node_cli["Pipeline CLI<br/>[cli.py]"]
  node_updater["Cricsheet updater<br/>[data_updater.py]"]
end

node_browser(("Fantasy user"))
node_espn(("ESPN profile service"))

node_browser -->|"selects matchup"| node_home
node_home -->|"selects matchup"| node_app
node_app -->|"routes to"| node_matchview
node_app -->|"routes to"| node_results
node_matchview -.->|"requests data"| node_client
node_results -.->|"starts generation"| node_generatehook
node_generatehook -.->|"uses API"| node_client
node_client -->|"HTTP and SSE"| node_apiapp
node_apiapp -->|"registers"| node_playerroute
node_apiapp -->|"registers"| node_teamroute
node_apiapp -->|"registers"| node_constraints
node_apiapp -->|"registers"| node_roster
node_apiapp -->|"registers"| node_matchroute
node_playerroute -->|"builds profiles"| node_profiles
node_playerroute -->|"reads cache"| node_cache
node_teamroute -->|"builds profiles"| node_profiles
node_teamroute -->|"generates teams"| node_generator
node_teamroute -->|"uses runtime data"| node_cache
node_constraints -->|"reads constraints"| node_generator
node_constraints -->|"uses cache"| node_cache
node_roster -->|"updates overrides"| node_cache
node_matchroute -->|"reads franchises"| node_cache
node_profiles -->|"reads player data"| node_cache
node_profiles -->|"predicts form"| node_hmm
node_profiles -->|"computes credits"| node_credit
node_cache -->|"initializes predictor"| node_hmm
node_hmm -->|"uses model"| node_generalhmm
node_hmm -->|"uses model"| node_shortterm
node_generator -->|"returns recommendations"| node_results
node_generatehook -->|"streams progress"| node_evolution
node_cli -->|"runs pipeline"| node_pipeline
node_cli -->|"updates source data"| node_updater
node_pipeline -->|"iterates matches"| node_loader
node_pipeline -->|"gets cached records"| node_smartcache
node_pipeline -->|"resolves roles"| node_roles
node_pipeline -->|"scores records"| node_scoring
node_smartcache -->|"parses uncached files"| node_parser
node_parser -.->|"produces match records"| node_scoring
node_cli -->|"applies ratings"| node_elo
node_cli -->|"fetches photos"| node_profilesfetch
node_playerroute -->|"fetches roster photos"| node_profilesfetch
node_profilesfetch -->|"fetches headshots"| node_espn
node_elo -.->|"supplies Elo dataset"| node_cache
node_features -.->|"supports prediction"| node_hmm

click node_home "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/pages/Home.tsx"
click node_app "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/App.tsx"
click node_matchview "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/pages/Match.tsx"
click node_results "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/pages/Results.tsx"
click node_generatehook "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/hooks/useGenerate.ts"
click node_client "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/api/client.ts"
click node_evolution "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/components/evolution/EvolutionDashboard.tsx"
click node_apiapp "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/app.py"
click node_playerroute "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/players.py"
click node_teamroute "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/teams.py"
click node_constraints "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/constraints.py"
click node_roster "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/roster.py"
click node_matchroute "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/match.py"
click node_cache "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/data_cache.py"
click node_profiles "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/player_service.py"
click node_hmm "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/hmm/predictor.py"
click node_shortterm "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/hmm/short_term_hmm.py"
click node_generalhmm "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/hmm/general_hmm.py"
click node_credit "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/credit_engine.py"
click node_elo "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/elo_engine.py"
click node_generator "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/team_generator.py"
click node_pipeline "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/pipeline.py"
click node_loader "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/match_loader.py"
click node_parser "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/match_parser.py"
click node_smartcache "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/utils/smart_cache.py"
click node_roles "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/role_resolver.py"
click node_scoring "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/scoring.py"
click node_cli "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/cli.py"
click node_updater "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/data_updater.py"
click node_features "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/form_features.py"
click node_profilesfetch "https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/profile_fetcher.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_app,node_matchview,node_results,node_generatehook,node_client,node_evolution,node_browser toneBlue
class node_apiapp,node_playerroute,node_teamroute,node_constraints,node_roster,node_matchroute toneAmber
class node_cache,node_profiles,node_hmm,node_shortterm,node_generalhmm,node_credit,node_elo,node_features,node_profilesfetch toneMint
class node_generator toneRose
class node_pipeline,node_loader,node_parser,node_smartcache,node_roles,node_scoring,node_cli,node_updater,node_espn toneIndigo
```

## Components

### Fantasy web app

- [Match selection](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [App routing](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Match workspace](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/pages/Match.tsx): `frontend/src/pages/Match.tsx`
- [Team results](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/pages/Results.tsx): `frontend/src/pages/Results.tsx`
- [Generation stream](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/hooks/useGenerate.ts): `frontend/src/hooks/useGenerate.ts`
- [API client](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [GA evolution view](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/frontend/src/components/evolution/EvolutionDashboard.tsx): `frontend/src/components/evolution/EvolutionDashboard.tsx`

### Flask API

- [Flask application](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/app.py): `backend/app.py`
- [Player endpoints](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/players.py): `backend/routes/players.py`
- [Team generation endpoints](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/teams.py): `backend/routes/teams.py`
- [Constraint endpoints](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/constraints.py): `backend/routes/constraints.py`
- [Roster controls](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/roster.py): `backend/routes/roster.py`
- [Franchise listing](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/routes/match.py): `backend/routes/match.py`

### Player analytics

- [Runtime data cache](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/data_cache.py): `backend/data_cache.py`
- [Player profiles](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/player_service.py): `backend/services/player_service.py`
- [Form prediction](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/hmm/predictor.py): `backend/core/hmm/predictor.py`
- [Player HMM](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/hmm/short_term_hmm.py): `backend/core/hmm/short_term_hmm.py`
- [General HMM](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/hmm/general_hmm.py): `backend/core/hmm/general_hmm.py`
- [Fantasy credits](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/credit_engine.py): `backend/services/credit_engine.py`
- [Elo ratings](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/elo_engine.py): `backend/core/elo_engine.py`
- [Form features](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/form_features.py): `backend/core/form_features.py`
- [Headshot fetching](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/profile_fetcher.py): `backend/services/profile_fetcher.py`

### Team optimization

- [Genetic optimizer](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/team_generator.py): `backend/services/team_generator.py`

### Data preparation

- [Match scoring pipeline](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/pipeline.py): `backend/jobs/pipeline.py`
- [Match file loader](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/match_loader.py): `backend/jobs/match_loader.py`
- [Match parser](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/match_parser.py): `backend/jobs/match_parser.py`
- [Parsed match cache](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/utils/smart_cache.py): `backend/utils/smart_cache.py`
- [Role resolution](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/services/role_resolver.py): `backend/services/role_resolver.py`
- [Fantasy point scoring](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/core/scoring.py): `backend/core/scoring.py`
- [Pipeline CLI](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/cli.py): `backend/cli.py`
- [Cricsheet updater](https://github.com/asim-shoaib/fantasypredictorserver/blob/main/backend/jobs/data_updater.py): `backend/jobs/data_updater.py`

### Other components

- **Fantasy user**
- **ESPN profile service**

## Connections

- Fantasy user → Match selection: selects matchup (evidence: `README.md`)
- Match selection → App routing: selects matchup (evidence: `frontend/src/App.tsx`)
- App routing → Match workspace: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Team results: routes to (evidence: `frontend/src/App.tsx`)
- Match workspace → API client: requests data
- Team results → Generation stream: starts generation
- Generation stream → API client: uses API
- API client → Flask application: HTTP and SSE (evidence: `README.md`)
- Flask application → Player endpoints: registers (evidence: `backend/app.py`)
- Flask application → Team generation endpoints: registers (evidence: `backend/app.py`)
- Flask application → Constraint endpoints: registers (evidence: `backend/app.py`)
- Flask application → Roster controls: registers (evidence: `backend/app.py`)
- Flask application → Franchise listing: registers (evidence: `backend/app.py`)
- Player endpoints → Player profiles: builds profiles (evidence: `backend/routes/players.py`)
- Player endpoints → Runtime data cache: reads cache (evidence: `backend/routes/players.py`)
- Team generation endpoints → Player profiles: builds profiles (evidence: `backend/routes/teams.py`)
- Team generation endpoints → Genetic optimizer: generates teams (evidence: `backend/routes/teams.py`)
- Team generation endpoints → Runtime data cache: uses runtime data (evidence: `backend/routes/teams.py`)
- Constraint endpoints → Genetic optimizer: reads constraints (evidence: `backend/routes/constraints.py`)
- Constraint endpoints → Runtime data cache: uses cache (evidence: `backend/routes/constraints.py`)
- Roster controls → Runtime data cache: updates overrides (evidence: `backend/routes/roster.py`)
- Franchise listing → Runtime data cache: reads franchises (evidence: `backend/routes/match.py`)
- Player profiles → Runtime data cache: reads player data (evidence: `backend/services/player_service.py`)
- Player profiles → Form prediction: predicts form (evidence: `backend/services/player_service.py`)
- Player profiles → Fantasy credits: computes credits (evidence: `backend/services/player_service.py`)
- Runtime data cache → Form prediction: initializes predictor (evidence: `backend/data_cache.py`)
- Form prediction → General HMM: uses model (evidence: `backend/core/hmm/predictor.py`)
- Form prediction → Player HMM: uses model (evidence: `backend/core/hmm/predictor.py`)
- Genetic optimizer → Team results: returns recommendations (evidence: `README.md`)
- Generation stream → GA evolution view: streams progress (evidence: `README.md`)
- Pipeline CLI → Match scoring pipeline: runs pipeline (evidence: `backend/cli.py`)
- Pipeline CLI → Cricsheet updater: updates source data (evidence: `backend/cli.py`)
- Match scoring pipeline → Match file loader: iterates matches (evidence: `backend/jobs/pipeline.py`)
- Match scoring pipeline → Parsed match cache: gets cached records (evidence: `backend/jobs/pipeline.py`)
- Match scoring pipeline → Role resolution: resolves roles (evidence: `backend/jobs/pipeline.py`)
- Match scoring pipeline → Fantasy point scoring: scores records (evidence: `backend/jobs/pipeline.py`)
- Parsed match cache → Match parser: parses uncached files (evidence: `backend/utils/smart_cache.py`)
- Match parser → Fantasy point scoring: produces match records
- Pipeline CLI → Elo ratings: applies ratings (evidence: `backend/cli.py`)
- Pipeline CLI → Headshot fetching: fetches photos (evidence: `backend/cli.py`)
- Player endpoints → Headshot fetching: fetches roster photos (evidence: `backend/routes/players.py`)
- Headshot fetching → ESPN profile service: fetches headshots (evidence: `backend/services/profile_fetcher.py`)
- Elo ratings → Runtime data cache: supplies Elo dataset
- Form features → Form prediction: supports prediction
