# akhanal222/nba-non-betting-app architecture

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

- Interactive diagram: https://gitdiagram.com/akhanal222/nba-non-betting-app
- Repository: https://github.com/akhanal222/nba-non-betting-app
- Video tour (about a minute): https://gitdiagram.com/akhanal222/nba-non-betting-app/video

## Overview

This is an NBA statistics and analysis application: users browse games, teams, players, standings, and leaderboards, then inspect player trends, matchups, comparisons, and prop projections with AI explanations. The React frontend calls a Spring REST backend; documented backend layers persist data in PostgreSQL and ingest NBA data from Balldontlie. The graph preserves those product branches and the documented nightly defense-versus-position refresh. Some subsystem links are based on the README and module names because their implementation was not sampled.

Main entry points: [`frontend/src/main.jsx`](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/main.jsx) (Page routing), [`frontend/src/api.js`](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/api.js) (API client), [`src/main/java/com/nba/nbanonbettingapp/repository`](https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/repository) (JPA repositories), [`src/main/java/com/nba/nbanonbettingapp/controller/AiExplanationController.java`](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/AiExplanationController.java) (AI explanation endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_routes["Page routing<br/>[main.jsx]"]
  node_home["Home and search<br/>[App.jsx]"]
  node_webclient["API client<br/>[api.js]"]
  node_matchupspage["Matchup dashboard"]
  node_predictionspage["Predictions page"]
  node_playerpage["Player detail"]
  node_rosterpage["Team players"]
  node_gamespage["Game lineups<br/>[Gamelineuppage.jsx]"]
  node_leaderspage["Top players<br/>[TopPlayers.jsx]"]
  node_standingspage["Team standings<br/>[TeamsStanding.jsx]"]
end

subgraph group_api["REST API"]
  node_controllers["REST controllers"]
  node_bdlcontroller["Balldontlie endpoints"]
  node_matchcontroller["Matchup endpoint"]
  node_aicontroller["AI explanation endpoint"]
end

subgraph group_analysis["Analysis services"]
  node_analysisservices["Analysis services"]
  node_matchservice["Head-to-head analysis"]
  node_projection["Prop projections"]
  node_comparison["Player comparisons"]
  node_dvp["Defense by position"]
  node_ewma["Advanced stats and EWMA"]
  node_gemini["AI explanations<br/>[GeminiService.java]"]
end

subgraph group_data["Data and integrations"]
  node_bdlservice["Balldontlie integration"]
  node_search["Player search and upsert"]
  node_repositories["JPA repositories"]
  node_advrepo["Advanced stats repository"]
  node_database[("Neon PostgreSQL")]
end

node_fan(("NBA fan"))
node_balldontlie{{"Balldontlie API"}}
node_geminiapi{{"Gemini API"}}

node_fan -->|"browses"| node_routes
node_routes -->|"renders"| node_home
node_routes -->|"routes to"| node_matchupspage
node_routes -->|"routes to"| node_predictionspage
node_routes -->|"routes to"| node_playerpage
node_routes -->|"routes to"| node_rosterpage
node_routes -->|"routes to"| node_gamespage
node_routes -->|"routes to"| node_leaderspage
node_routes -->|"routes to"| node_standingspage
node_home -->|"requests data"| node_webclient
node_matchupspage -->|"requests data"| node_webclient
node_predictionspage -->|"requests data"| node_webclient
node_playerpage -->|"requests data"| node_webclient
node_rosterpage -->|"requests data"| node_webclient
node_gamespage -->|"requests data"| node_webclient
node_leaderspage -->|"requests data"| node_webclient
node_standingspage -->|"requests data"| node_webclient
node_webclient -->|"calls REST"| node_controllers
node_controllers -->|"delegates requests"| node_analysisservices
node_bdlcontroller -->|"calls"| node_bdlservice
node_matchcontroller -->|"calls"| node_matchservice
node_aicontroller -->|"requests prediction"| node_projection
node_aicontroller -->|"requests matchup"| node_matchservice
node_aicontroller -->|"requests comparison"| node_comparison
node_aicontroller -->|"requests explanation"| node_gemini
node_matchservice -->|"reads stats"| node_repositories
node_projection -->|"reads stats"| node_repositories
node_comparison -->|"reads player data"| node_repositories
node_search -->|"searches and saves"| node_repositories
node_bdlservice -->|"fetches NBA data"| node_balldontlie
node_search -->|"searches fallback"| node_bdlservice
node_ewma -->|"fetches advanced stats"| node_bdlservice
node_ewma -->|"upserts rows"| node_advrepo
node_dvp -->|"reads and saves"| node_repositories
node_gemini -->|"generates text"| node_geminiapi
node_gemini -->|"reads and caches"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_advrepo -->|"reads and writes"| node_database

click node_routes "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/main.jsx"
click node_home "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/App.jsx"
click node_webclient "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/api.js"
click node_matchupspage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/MatchupsDashboard.jsx"
click node_predictionspage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/PlayersPredictions.jsx"
click node_playerpage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/PlayerDetailPage.jsx"
click node_rosterpage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/TeamPlayersPage.jsx"
click node_gamespage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/Gamelineuppage.jsx"
click node_leaderspage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/TopPlayers.jsx"
click node_standingspage "https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/TeamsStanding.jsx"
click node_controllers "https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/controller"
click node_bdlcontroller "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/BalldontlieController.java"
click node_matchcontroller "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/HeadToHeadController.java"
click node_aicontroller "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/AiExplanationController.java"
click node_analysisservices "https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/service"
click node_matchservice "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/HeadToHeadService.java"
click node_projection "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/PropProjectionService.java"
click node_comparison "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/PlayerComparisonService.java"
click node_dvp "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/DvPIngestionService.java"
click node_ewma "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/AdvancedStatsIngestionService.java"
click node_gemini "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/GeminiService.java"
click node_bdlservice "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/BalldontlieService.java"
click node_search "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/PlayerSearchService.java"
click node_repositories "https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/repository"
click node_advrepo "https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/repository/PlayerAdvancedStatsRepository.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_routes,node_home,node_webclient,node_matchupspage,node_predictionspage,node_playerpage,node_rosterpage,node_gamespage,node_leaderspage,node_standingspage toneBlue
class node_controllers,node_bdlcontroller,node_matchcontroller,node_aicontroller toneAmber
class node_analysisservices,node_matchservice,node_projection,node_comparison,node_dvp,node_ewma,node_gemini,node_balldontlie,node_geminiapi toneMint
class node_bdlservice,node_search,node_repositories,node_advrepo,node_database toneRose
class node_fan toneIndigo
```

## Components

### Web experience

- [Page routing](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Home and search](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Matchup dashboard](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/MatchupsDashboard.jsx): `frontend/src/pages/MatchupsDashboard.jsx`
- [Predictions page](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/PlayersPredictions.jsx): `frontend/src/pages/PlayersPredictions.jsx`
- [Player detail](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/PlayerDetailPage.jsx): `frontend/src/pages/PlayerDetailPage.jsx`
- [Team players](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/TeamPlayersPage.jsx): `frontend/src/pages/TeamPlayersPage.jsx`
- [Game lineups](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/Gamelineuppage.jsx): `frontend/src/pages/Gamelineuppage.jsx`
- [Top players](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/TopPlayers.jsx): `frontend/src/pages/TopPlayers.jsx`
- [Team standings](https://github.com/akhanal222/nba-non-betting-app/blob/main/frontend/src/pages/TeamsStanding.jsx): `frontend/src/pages/TeamsStanding.jsx`

### REST API

- [REST controllers](https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/controller): `src/main/java/com/nba/nbanonbettingapp/controller`
- [Balldontlie endpoints](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/BalldontlieController.java): `src/main/java/com/nba/nbanonbettingapp/controller/BalldontlieController.java`
- [Matchup endpoint](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/HeadToHeadController.java): `src/main/java/com/nba/nbanonbettingapp/controller/HeadToHeadController.java`
- [AI explanation endpoint](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/controller/AiExplanationController.java): `src/main/java/com/nba/nbanonbettingapp/controller/AiExplanationController.java`

### Analysis services

- [Analysis services](https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/service): `src/main/java/com/nba/nbanonbettingapp/service`
- [Head-to-head analysis](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/HeadToHeadService.java): `src/main/java/com/nba/nbanonbettingapp/service/HeadToHeadService.java`
- [Prop projections](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/PropProjectionService.java): `src/main/java/com/nba/nbanonbettingapp/service/PropProjectionService.java`
- [Player comparisons](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/PlayerComparisonService.java): `src/main/java/com/nba/nbanonbettingapp/service/PlayerComparisonService.java`
- [Defense by position](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/DvPIngestionService.java): `src/main/java/com/nba/nbanonbettingapp/service/DvPIngestionService.java`
- [Advanced stats and EWMA](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/AdvancedStatsIngestionService.java): `src/main/java/com/nba/nbanonbettingapp/service/AdvancedStatsIngestionService.java`
- [AI explanations](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/GeminiService.java): `src/main/java/com/nba/nbanonbettingapp/service/GeminiService.java`

### Data and integrations

- [Balldontlie integration](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/BalldontlieService.java): `src/main/java/com/nba/nbanonbettingapp/service/BalldontlieService.java`
- [Player search and upsert](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/service/PlayerSearchService.java): `src/main/java/com/nba/nbanonbettingapp/service/PlayerSearchService.java`
- [JPA repositories](https://github.com/akhanal222/nba-non-betting-app/tree/main/src/main/java/com/nba/nbanonbettingapp/repository): `src/main/java/com/nba/nbanonbettingapp/repository`
- [Advanced stats repository](https://github.com/akhanal222/nba-non-betting-app/blob/main/src/main/java/com/nba/nbanonbettingapp/repository/PlayerAdvancedStatsRepository.java): `src/main/java/com/nba/nbanonbettingapp/repository/PlayerAdvancedStatsRepository.java`
- **Neon PostgreSQL**

### Other components

- **NBA fan**
- **Balldontlie API**
- **Gemini API**

## Connections

- NBA fan → Page routing: browses
- Page routing → Home and search: renders
- Page routing → Matchup dashboard: routes to
- Page routing → Predictions page: routes to
- Page routing → Player detail: routes to
- Page routing → Team players: routes to
- Page routing → Game lineups: routes to
- Page routing → Top players: routes to
- Page routing → Team standings: routes to
- Home and search → API client: requests data
- Matchup dashboard → API client: requests data
- Predictions page → API client: requests data
- Player detail → API client: requests data
- Team players → API client: requests data
- Game lineups → API client: requests data
- Top players → API client: requests data
- Team standings → API client: requests data
- API client → REST controllers: calls REST
- REST controllers → Analysis services: delegates requests
- Balldontlie endpoints → Balldontlie integration: calls
- Matchup endpoint → Head-to-head analysis: calls
- AI explanation endpoint → Prop projections: requests prediction
- AI explanation endpoint → Head-to-head analysis: requests matchup
- AI explanation endpoint → Player comparisons: requests comparison
- AI explanation endpoint → AI explanations: requests explanation
- Head-to-head analysis → JPA repositories: reads stats
- Prop projections → JPA repositories: reads stats
- Player comparisons → JPA repositories: reads player data
- Player search and upsert → JPA repositories: searches and saves
- Balldontlie integration → Balldontlie API: fetches NBA data
- Player search and upsert → Balldontlie integration: searches fallback
- Advanced stats and EWMA → Balldontlie integration: fetches advanced stats
- Advanced stats and EWMA → Advanced stats repository: upserts rows
- Defense by position → JPA repositories: reads and saves
- AI explanations → Gemini API: generates text
- AI explanations → JPA repositories: reads and caches
- JPA repositories → Neon PostgreSQL: reads and writes
- Advanced stats repository → Neon PostgreSQL: reads and writes