# xbhoomi-ar/fantasy-xi architecture

> Architecture diagram of the GitHub repository xbhoomi-ar/fantasy-xi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xbhoomi-ar/fantasy-xi
- Repository: https://github.com/xbhoomi-ar/fantasy-xi

## Overview

FantasyXI is an FPL decision-support product that predicts player points, chooses a weekly strategy, optimizes a legal squad and starting XI, then carries season state into the next gameweek. Its primary user workflow is the local browser demo: start a season, request subsequent gameweeks, and view the returned squad, transfers, chips and budget. The README also documents two interchangeable prediction models and a PPO-free historical baseline. The backend and frontend excerpts establish the demo wiring; some internal PPO-to-optimizer wiring is documented in the README but not shown in sampled source.

Main entry points: [`rl_decision_layer/ppo/env.py`](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/ppo/env.py) (PPO environment), [`rl_decision_layer/historical_loop.py`](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/historical_loop.py) (MILP baseline), [`backend/rl_bridge.py`](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/rl_bridge.py) (RL bridge), [`rl_decision_layer/predictions/interface.py`](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/predictions/interface.py) (Canonical predictions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prediction["Prediction"]
  node_bilstm["BiLSTM predictor"]
  node_xgb_features["XGBoost features<br/>[features.py]"]
  node_xgb_model["XGBoost predictor<br/>[train.py]"]
  node_prediction_adapter["Canonical predictions<br/>[interface.py]"]
end

subgraph group_decision["Decision"]
  node_candidate_pool["Candidate pipeline<br/>[pipeline.py]"]
  node_ppo["PPO strategy"]
  node_ppo_environment["PPO environment<br/>[env.py]"]
end

subgraph group_optimization["Optimization"]
  node_squad_optimizer["Squad MILP<br/>[squad_milp.py]"]
  node_xi_optimizer["Starting XI<br/>[starting_xi.py]"]
  node_chip_strategy["Chip strategy<br/>[chip_strategy.py]"]
end

subgraph group_season["Season Runtime"]
  node_historical_environment["Historical environment<br/>[historical_env.py]"]
  node_season_controller["Sequential season runner"]
  node_baseline_loop["MILP baseline<br/>[historical_loop.py]"]
  node_season_state[("Season session state<br/>[rl_bridge.py]")]
end

subgraph group_demo["Local Demo"]
  node_frontend["Demo UI<br/>[app.js]"]
  node_api["FastAPI<br/>[app.py]"]
  node_bridge["RL bridge<br/>[rl_bridge.py]"]
end

node_historical_data[("Historical player data")]
node_browser_user(("Browser user"))

node_historical_data -.->|"trains on"| node_bilstm
node_historical_data -.->|"builds features"| node_xgb_features
node_xgb_features -->|"provides features"| node_xgb_model
node_bilstm -->|"loads predictions"| node_prediction_adapter
node_xgb_model -->|"loads predictions"| node_prediction_adapter
node_prediction_adapter -->|"provides predictions"| node_candidate_pool
node_candidate_pool -->|"supplies candidates"| node_ppo_environment
node_ppo -->|"policy acts in"| node_ppo_environment
node_ppo_environment -->|"strategy guides"| node_squad_optimizer
node_ppo_environment -->|"chooses chip"| node_chip_strategy
node_squad_optimizer -->|"selects squad for"| node_xi_optimizer
node_season_controller -->|"steps gameweeks"| node_ppo_environment
node_historical_environment -->|"requests candidates"| node_candidate_pool
node_baseline_loop -->|"steps history"| node_historical_environment
node_baseline_loop -->|"requests decisions"| node_squad_optimizer
node_baseline_loop -->|"selects starters"| node_xi_optimizer
node_baseline_loop -->|"loads predictions"| node_prediction_adapter
node_browser_user -->|"starts season"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"dispatches requests"| node_bridge
node_bridge -->|"runs season"| node_season_controller
node_bridge -->|"stores session"| node_season_state
node_season_state -->|"restores session"| node_bridge

click node_bilstm "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/models/BiLSTM_model/gate_architecture/kaggle_dual_expert_full.py"
click node_xgb_features "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/models/xgboost_model/src/fpl_predictor/features.py"
click node_xgb_model "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/models/xgboost_model/src/fpl_predictor/train.py"
click node_prediction_adapter "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/predictions/interface.py"
click node_candidate_pool "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/candidates/pipeline.py"
click node_ppo "https://github.com/xbhoomi-ar/fantasy-xi/tree/main/rl_decision_layer/ppo"
click node_ppo_environment "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/ppo/env.py"
click node_squad_optimizer "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/optimization/squad_milp.py"
click node_xi_optimizer "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/optimization/starting_xi.py"
click node_chip_strategy "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/optimization/chip_strategy.py"
click node_historical_environment "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/environment/historical_env.py"
click node_season_controller "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/ppo/season_controller.py"
click node_baseline_loop "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/historical_loop.py"
click node_frontend "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/frontend/app.js"
click node_api "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/app.py"
click node_bridge "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/rl_bridge.py"
click node_season_state "https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/rl_bridge.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_bilstm,node_xgb_features,node_xgb_model,node_prediction_adapter,node_browser_user toneBlue
class node_candidate_pool,node_ppo,node_ppo_environment,node_historical_data toneAmber
class node_squad_optimizer,node_xi_optimizer,node_chip_strategy toneMint
class node_historical_environment,node_season_controller,node_baseline_loop,node_season_state toneRose
class node_frontend,node_api,node_bridge toneIndigo
```

## Components

### Prediction

- [BiLSTM predictor](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/models/BiLSTM_model/gate_architecture/kaggle_dual_expert_full.py): `models/BiLSTM_model/gate_architecture/kaggle_dual_expert_full.py`
- [XGBoost features](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/models/xgboost_model/src/fpl_predictor/features.py): `models/xgboost_model/src/fpl_predictor/features.py`
- [XGBoost predictor](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/models/xgboost_model/src/fpl_predictor/train.py): `models/xgboost_model/src/fpl_predictor/train.py`
- [Canonical predictions](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/predictions/interface.py): `rl_decision_layer/predictions/interface.py`

### Decision

- [Candidate pipeline](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/candidates/pipeline.py): `rl_decision_layer/candidates/pipeline.py`
- [PPO strategy](https://github.com/xbhoomi-ar/fantasy-xi/tree/main/rl_decision_layer/ppo): `rl_decision_layer/ppo`
- [PPO environment](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/ppo/env.py): `rl_decision_layer/ppo/env.py`

### Optimization

- [Squad MILP](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/optimization/squad_milp.py): `rl_decision_layer/optimization/squad_milp.py`
- [Starting XI](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/optimization/starting_xi.py): `rl_decision_layer/optimization/starting_xi.py`
- [Chip strategy](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/optimization/chip_strategy.py): `rl_decision_layer/optimization/chip_strategy.py`

### Season Runtime

- [Historical environment](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/environment/historical_env.py): `rl_decision_layer/environment/historical_env.py`
- [Sequential season runner](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/ppo/season_controller.py): `rl_decision_layer/ppo/season_controller.py`
- [MILP baseline](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/rl_decision_layer/historical_loop.py): `rl_decision_layer/historical_loop.py`
- [Season session state](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/rl_bridge.py): `backend/rl_bridge.py`

### Local Demo

- [Demo UI](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/frontend/app.js): `frontend/app.js`
- [FastAPI](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/app.py): `backend/app.py`
- [RL bridge](https://github.com/xbhoomi-ar/fantasy-xi/blob/main/backend/rl_bridge.py): `backend/rl_bridge.py`

### Other components

- **Historical player data**
- **Browser user**

## Connections

- Historical player data → BiLSTM predictor: trains on
- Historical player data → XGBoost features: builds features
- XGBoost features → XGBoost predictor: provides features
- BiLSTM predictor → Canonical predictions: loads predictions
- XGBoost predictor → Canonical predictions: loads predictions
- Canonical predictions → Candidate pipeline: provides predictions
- Candidate pipeline → PPO environment: supplies candidates
- PPO strategy → PPO environment: policy acts in
- PPO environment → Squad MILP: strategy guides
- PPO environment → Chip strategy: chooses chip
- Squad MILP → Starting XI: selects squad for
- Sequential season runner → PPO environment: steps gameweeks
- Historical environment → Candidate pipeline: requests candidates
- MILP baseline → Historical environment: steps history
- MILP baseline → Squad MILP: requests decisions
- MILP baseline → Starting XI: selects starters
- MILP baseline → Canonical predictions: loads predictions
- Browser user → Demo UI: starts season
- Demo UI → FastAPI: calls API
- FastAPI → RL bridge: dispatches requests
- RL bridge → Sequential season runner: runs season
- RL bridge → Season session state: stores session
- Season session state → RL bridge: restores session