# gabriel15vitor/nba-predictions architecture

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

- Interactive diagram: https://gitdiagram.com/gabriel15vitor/nba-predictions
- Repository: https://github.com/gabriel15vitor/nba-predictions

## Overview

NBA win-probability and championship-ranking API with a lightweight web UI and separate Python data-ingestion scripts. The principal workflow is a user selecting teams in the UI, requesting a matchup or ranking, and receiving JSON predictions based on latest-season team statistics and active roster strength. Separate ingestion scripts fetch NBA statistics and submit batch data to the API; roster management supports injury flags and pruning. The graph follows the documented layered design; unsampled frontend/API wiring is shown only where the README documents it.

Main entry points: [`nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/PlayerRepository.java`](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/PlayerRepository.java) (Player queries), [`nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/TeamStatsRepository.java`](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/TeamStatsRepository.java) (Team stats queries), [`nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java`](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java) (Scoring and ranking), [`nba-predictor/src/main/resources/static`](https://github.com/gabriel15vitor/nba-predictions/tree/main/nba-predictor/src/main/resources/static) (Prediction and roster UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_nba(("NBA stats API"))
  node_fetchplayers["Fetch players<br/>[fetch_players.py]"]
  node_fetchstats["Fetch team stats"]
end

subgraph group_api["REST API"]
  node_playerapi["Player endpoints"]
  node_statsapi["Team stats endpoints"]
  node_predictionapi["Prediction endpoints"]
  node_playersvc["Roster management<br/>[PlayerService.java]"]
  node_statssvc["Stats ingestion"]
end

subgraph group_prediction["Prediction"]
  node_predsvc["Scoring and ranking"]
  node_response["Prediction results"]
end

subgraph group_storage["Persistence"]
  node_playerrepo["Player queries"]
  node_statsrepo["Team stats queries"]
  node_playermodel[("Player records<br/>[Player.java]")]
  node_statsmodel[("Season team records<br/>[TeamStats.java]")]
  node_postgres[("PostgreSQL")]
end

subgraph group_ui["Web interface"]
  node_web["Prediction and roster UI"]
end

node_user(("User"))

node_nba -->|"provides stats"| node_fetchplayers
node_nba -->|"provides stats"| node_fetchstats
node_fetchplayers -->|"posts batches"| node_playerapi
node_fetchstats -->|"posts batches"| node_statsapi
node_user -->|"uses"| node_web
node_web -->|"requests predictions"| node_predictionapi
node_web -->|"manages roster"| node_playerapi
node_web -->|"lists teams"| node_statsapi
node_playerapi -->|"delegates updates"| node_playersvc
node_playerapi -->|"reads roster"| node_playerrepo
node_statsapi -->|"delegates batches"| node_statssvc
node_statsapi -->|"queries teams"| node_statsrepo
node_predictionapi -->|"requests scores"| node_predsvc
node_predsvc -->|"loads season stats"| node_statsrepo
node_predsvc -->|"loads active rosters"| node_playerrepo
node_predsvc -->|"builds results"| node_response
node_playersvc -->|"upserts and prunes"| node_playerrepo
node_statssvc -->|"checks and saves"| node_statsrepo
node_playerrepo -->|"queries"| node_playermodel
node_statsrepo -->|"queries"| node_statsmodel
node_playerrepo -->|"persists via JPA"| node_postgres
node_statsrepo -->|"persists via JPA"| node_postgres

click node_fetchplayers "https://github.com/gabriel15vitor/nba-predictions/blob/main/data-scripts/fetch_players.py"
click node_fetchstats "https://github.com/gabriel15vitor/nba-predictions/blob/main/data-scripts/fetch_team_stats.py"
click node_web "https://github.com/gabriel15vitor/nba-predictions/tree/main/nba-predictor/src/main/resources/static"
click node_playerapi "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PlayerController.java"
click node_statsapi "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/TeamStatsController.java"
click node_predictionapi "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PredictionController.java"
click node_playersvc "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PlayerService.java"
click node_statssvc "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/TeamStatsService.java"
click node_predsvc "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java"
click node_response "https://github.com/gabriel15vitor/nba-predictions/tree/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model"
click node_playerrepo "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/PlayerRepository.java"
click node_statsrepo "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/TeamStatsRepository.java"
click node_playermodel "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model/Player.java"
click node_statsmodel "https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model/TeamStats.java"

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_nba,node_fetchplayers,node_fetchstats,node_user toneBlue
class node_playerapi,node_statsapi,node_predictionapi,node_playersvc,node_statssvc toneAmber
class node_predsvc,node_response toneMint
class node_playerrepo,node_statsrepo,node_playermodel,node_statsmodel,node_postgres toneRose
class node_web toneIndigo
```

## Components

### Data ingestion

- **NBA stats API**
- [Fetch players](https://github.com/gabriel15vitor/nba-predictions/blob/main/data-scripts/fetch_players.py): `data-scripts/fetch_players.py`
- [Fetch team stats](https://github.com/gabriel15vitor/nba-predictions/blob/main/data-scripts/fetch_team_stats.py): `data-scripts/fetch_team_stats.py`

### REST API

- [Player endpoints](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PlayerController.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PlayerController.java`
- [Team stats endpoints](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/TeamStatsController.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/TeamStatsController.java`
- [Prediction endpoints](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PredictionController.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PredictionController.java`
- [Roster management](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PlayerService.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PlayerService.java`
- [Stats ingestion](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/TeamStatsService.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/TeamStatsService.java`

### Prediction

- [Scoring and ranking](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java`
- [Prediction results](https://github.com/gabriel15vitor/nba-predictions/tree/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model`

### Persistence

- [Player queries](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/PlayerRepository.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/PlayerRepository.java`
- [Team stats queries](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/TeamStatsRepository.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/TeamStatsRepository.java`
- [Player records](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model/Player.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model/Player.java`
- [Season team records](https://github.com/gabriel15vitor/nba-predictions/blob/main/nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model/TeamStats.java): `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/model/TeamStats.java`
- **PostgreSQL**

### Web interface

- [Prediction and roster UI](https://github.com/gabriel15vitor/nba-predictions/tree/main/nba-predictor/src/main/resources/static): `nba-predictor/src/main/resources/static`

### Other components

- **User**

## Connections

- NBA stats API → Fetch players: provides stats (evidence: `readme.md`)
- NBA stats API → Fetch team stats: provides stats (evidence: `readme.md`)
- Fetch players → Player endpoints: posts batches (evidence: `readme.md`)
- Fetch team stats → Team stats endpoints: posts batches (evidence: `readme.md`)
- User → Prediction and roster UI: uses (evidence: `readme.md`)
- Prediction and roster UI → Prediction endpoints: requests predictions (evidence: `readme.md`)
- Prediction and roster UI → Player endpoints: manages roster (evidence: `readme.md`)
- Prediction and roster UI → Team stats endpoints: lists teams (evidence: `readme.md`)
- Player endpoints → Roster management: delegates updates (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PlayerController.java`)
- Player endpoints → Player queries: reads roster (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PlayerController.java`)
- Team stats endpoints → Stats ingestion: delegates batches (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/TeamStatsController.java`)
- Team stats endpoints → Team stats queries: queries teams (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/TeamStatsController.java`)
- Prediction endpoints → Scoring and ranking: requests scores (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/controller/PredictionController.java`)
- Scoring and ranking → Team stats queries: loads season stats (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java`)
- Scoring and ranking → Player queries: loads active rosters (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java`)
- Scoring and ranking → Prediction results: builds results (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PredictionService.java`)
- Roster management → Player queries: upserts and prunes (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/PlayerService.java`)
- Stats ingestion → Team stats queries: checks and saves (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/service/TeamStatsService.java`)
- Player queries → Player records: queries (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/PlayerRepository.java`)
- Team stats queries → Season team records: queries (evidence: `nba-predictor/src/main/java/com/gabrielbarbosa/nba_predictor/repository/TeamStatsRepository.java`)
- Player queries → PostgreSQL: persists via JPA (evidence: `readme.md`)
- Team stats queries → PostgreSQL: persists via JPA (evidence: `readme.md`)
