# tahmidfayaz/fpl-out-of-position-players architecture

> Architecture diagram of the GitHub repository tahmidfayaz/fpl-out-of-position-players, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tahmidfayaz/fpl-out-of-position-players
- Repository: https://github.com/tahmidfayaz/fpl-out-of-position-players

## Overview

1. This repository is a small, notebook-driven analytics project rather than a multi-service application. The core artifact is `FPL_OPP.ipynb`, which likely contains the full end-to-end workflow for loading data, engineering features, predicting positions, and flagging out-of-position players.

2. The only explicit data asset in the repo is `Season 23-24.csv`. This appears to be the primary input dataset and likely contains player/gameweek performance records for the 2023–24 Fantasy Premier League season.

3. The main data flow is straightforward: the notebook reads the CSV, transforms player/game data into model features or heuristics, then produces position predictions and out-of-position classifications. The notebook is therefore both the orchestrator and the analysis layer.

4. The repository’s purpose is analytical inference, not transaction processing. There is no evidence of an API, database, frontend, or background worker; results are probably inspected in notebook cells, tables, and charts.

5. The system boundary is the CSV file. All upstream data acquisition is external to the repo, and all downstream outputs are ephemeral notebook outputs unless the notebook explicitly exports results. That means the repo is best understood as a reproducible analysis pipeline over a static season snapshot.

6. The domain logic centers on comparing a player’s observed on-pitch behavior and performance metrics against their Fantasy Premier League position. The “out-of-position” concept is the key business rule: players whose role or usage differs from their official FPL classification are the target signal.

7. The likely internal stages are:
   - dataset loading and cleaning,
   - feature construction from match/player statistics,
   - position prediction or scoring,
   - identification of discrepancies between predicted and natural/assigned position,
   - presentation of flagged players.

8. Any modeling boundary is probably embedded in the notebook itself. Since there are no separate source modules in the tree, training, evaluation, and inference are likely not split into distinct services or packages; everything is coupled inside one exploratory workflow.

9. Tooling is notebook-centric and likely Python-based, but the repo does not contain packaging, test, or deployment infrastructure. Architecturally, this is closer to an analysis notebook with a data file than to a production system.

10. For diagramming, the most accurate structure is: external FPL/game data source into `Season 23-24.csv`, then into `FPL_OPP.ipynb`, then out to derived rankings/predictions/visualizations. The only durable artifacts in the repository are the notebook and the season dataset.

Main entry points: [`FPL_OPP.ipynb`](https://github.com/tahmidfayaz/fpl-out-of-position-players/blob/main/FPL_OPP.ipynb) (FPL notebook), [`Season 23-24.csv`](https://github.com/tahmidfayaz/fpl-out-of-position-players/blob/HEAD/Season%2023-24.csv) (Season CSV)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_external_fpl[("FPL data<br/>external source")]
  node_season_csv["Season CSV<br/>dataset<br/>[Season 23-24.csv]"]
end

subgraph group_analysis["Analysis"]
  node_notebook["FPL notebook<br/>analysis notebook<br/>[FPL_OPP.ipynb]"]
  node_cleaning["Clean data<br/>prep step"]
  node_features["Features<br/>feature build"]
  node_position_model{{"Position score<br/>model/heuristic"}}
  node_opp_logic{{"OOP logic<br/>classification rule"}}
end

subgraph group_outputs["Outputs"]
  node_rankings["Flagged players<br/>results table"]
  node_charts(("Visuals<br/>notebook output"))
end

node_external_fpl -->|"source data"| node_season_csv
node_season_csv -->|"loaded by"| node_notebook
node_notebook -->|"orchestrates"| node_cleaning
node_cleaning -->|"transforms into"| node_features
node_features -->|"feeds"| node_position_model
node_position_model -->|"evaluated by"| node_opp_logic
node_opp_logic -->|"produces"| node_rankings
node_opp_logic -->|"summarized in"| node_charts
node_notebook -.->|"emits"| node_rankings
node_notebook -.->|"emits"| node_charts

click node_season_csv "https://github.com/tahmidfayaz/fpl-out-of-position-players/blob/main/Season 23-24.csv"
click node_notebook "https://github.com/tahmidfayaz/fpl-out-of-position-players/blob/main/FPL_OPP.ipynb"

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_external_fpl,node_season_csv toneBlue
class node_notebook,node_cleaning,node_features,node_position_model,node_opp_logic toneAmber
class node_rankings,node_charts toneMint
```

## Components

### Inputs

Static season snapshot and upstream FPL data boundary.

- **FPL data**: external source · Upstream Fantasy Premier League and match data used to build the season snapshot.
- [Season CSV](https://github.com/tahmidfayaz/fpl-out-of-position-players/blob/HEAD/Season%2023-24.csv): dataset · Primary repo data asset containing 2023-24 player and gameweek records. · `Season 23-24.csv`

### Analysis

Notebook-driven workflow that cleans, models, and classifies players.

- [FPL notebook](https://github.com/tahmidfayaz/fpl-out-of-position-players/blob/main/FPL_OPP.ipynb): analysis notebook · Main orchestrator for loading data, transforming features, and running the full workflow. · `FPL_OPP.ipynb`
- **Clean data**: prep step · Notebook stage for loading, filtering, and normalizing the season snapshot.
- **Features**: feature build · Constructs player and match features from season statistics.
- **Position score**: model/heuristic · Predicts or scores likely player positions from engineered signals.
- **OOP logic**: classification rule · Compares predicted role against official FPL position to flag out-of-position players.

### Outputs

Ephemeral results produced in notebook cells.

- **Flagged players**: results table · Ranked or labeled players identified as out of position.
- **Visuals**: notebook output · Tables, charts, and exploratory cell outputs for inspection.

## Connections

- FPL data → Season CSV: source data · External FPL data is captured into the repository snapshot.
- Season CSV → FPL notebook: loaded by · The notebook reads the season CSV as the main input.
- FPL notebook → Clean data: orchestrates · Notebook cells drive the preprocessing workflow.
- Clean data → Features: transforms into · Cleaned records are converted into model-ready features.
- Features → Position score: feeds · Engineered signals support position prediction or scoring.
- Position score → OOP logic: evaluated by · Predicted position is compared with official FPL classification.
- OOP logic → Flagged players: produces · Players that violate the expected role are flagged.
- OOP logic → Visuals: summarized in · Results are inspected through notebook tables and visualizations.
- FPL notebook → Flagged players: emits · The notebook may render final ranked outputs directly.
- FPL notebook → Visuals: emits · The notebook presents intermediate and final visual summaries.