# mgomez1023/mens-league-mvp architecture

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

- Interactive diagram: https://gitdiagram.com/mgomez1023/mens-league-mvp
- Repository: https://github.com/mgomez1023/mens-league-mvp

## Overview

Men’s League MVP is a league-management application: visitors and league staff use a React web app to view games, teams, rosters, standings, rules, posts, and photos; authenticated managers and admins can maintain league data. The web client calls a FastAPI service, which routes public, authentication, and administrative requests and persists domain records. Standings calculation and image handling are distinct backend responsibilities. The source index and excerpts establish the main routing and selected calls; some page and API-to-router relationships are documented rather than directly excerpted.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/App.tsx) (App routing), [`apps/api/app/main.py`](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/main.py) (FastAPI application), [`apps/api/app/routers/admin.py`](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/admin.py) (Admin routes), [`apps/api/app/models.py`](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/models.py) (League models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_league["League operations"]
  node_home["League home<br/>[HomePage.tsx]"]
  node_games["Games management<br/>[GamesPage.tsx]"]
  node_teams["Team management<br/>[TeamsPage.tsx]"]
  node_roster["Player rosters<br/>[RosterPage.tsx]"]
  node_standingspage["Standings view<br/>[StandingsPage.tsx]"]
  node_leaguepages["Content pages"]
  node_csv["CSV import<br/>[CsvImportModal.tsx]"]
  node_csvutil["CSV processing<br/>[csvImport.ts]"]
  node_gameview["Game details"]
  node_gamecard["Public game card<br/>[PublicGameCard.tsx]"]
  node_leagueutil["League formatting<br/>[league.ts]"]
end

subgraph group_service["API service"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_authroute["Authentication routes<br/>[auth.py]"]
  node_publicroute["Public routes<br/>[public.py]"]
  node_adminroute["Admin routes<br/>[admin.py]"]
  node_security["Access control<br/>[deps.py]"]
  node_securityjwt["Token security<br/>[security.py]"]
end

subgraph group_domain["League data"]
  node_standings["Standings engine<br/>[standings.py]"]
  node_storage["Image storage<br/>[storage.py]"]
  node_models["League models<br/>[models.py]"]
  node_database[("Database sessions<br/>[db.py]")]
  node_config["Runtime settings<br/>[config.py]"]
end

node_visitor(("League user"))

node_visitor -.->|"uses"| node_app
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_games
node_app -->|"routes to"| node_teams
node_app -->|"routes to"| node_roster
node_app -->|"routes to"| node_standingspage
node_app -->|"routes to"| node_leaguepages
node_games -->|"requests data"| node_client
node_csv -->|"processes import"| node_csvutil
node_games -->|"opens import"| node_csv
node_games -->|"shows details"| node_gameview
node_gameview -->|"formats game"| node_leagueutil
node_gamecard -->|"formats game"| node_leagueutil
node_client -->|"HTTP requests"| node_backend
node_backend -->|"registers routes"| node_authroute
node_backend -->|"registers routes"| node_adminroute
node_backend -->|"registers routes"| node_publicroute
node_backend -->|"uses calculations"| node_standings
node_backend -->|"serves uploads"| node_storage
node_authroute -->|"validates access"| node_security
node_adminroute -->|"checks permissions"| node_security
node_publicroute -->|"requests rankings"| node_standings
node_adminroute -->|"updates rankings"| node_standings
node_adminroute -->|"handles images"| node_storage
node_publicroute -->|"resolves images"| node_storage
node_standings -->|"reads league data"| node_models
node_authroute -->|"loads users"| node_models
node_adminroute -->|"manages records"| node_models
node_publicroute -->|"reads records"| node_models
node_models -->|"maps tables"| node_database
node_database -->|"gets settings"| node_config
node_security -->|"uses JWT settings"| node_config
node_authroute -->|"issues tokens"| node_securityjwt

click node_app "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/App.tsx"
click node_client "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/api.ts"
click node_home "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/HomePage.tsx"
click node_games "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/GamesPage.tsx"
click node_teams "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/TeamsPage.tsx"
click node_roster "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/RosterPage.tsx"
click node_standingspage "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/StandingsPage.tsx"
click node_leaguepages "https://github.com/mgomez1023/mens-league-mvp/tree/main/apps/web/src/pages"
click node_csv "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/components/CsvImportModal.tsx"
click node_csvutil "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/utils/csvImport.ts"
click node_gameview "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/components/GameDetailsDialog.tsx"
click node_gamecard "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/components/PublicGameCard.tsx"
click node_leagueutil "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/utils/league.ts"
click node_backend "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/main.py"
click node_authroute "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/auth.py"
click node_publicroute "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/public.py"
click node_adminroute "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/admin.py"
click node_security "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/deps.py"
click node_securityjwt "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/security.py"
click node_standings "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/standings.py"
click node_storage "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/storage.py"
click node_models "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/models.py"
click node_database "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/db.py"
click node_config "https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/config.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_app,node_client,node_visitor toneBlue
class node_home,node_games,node_teams,node_roster,node_standingspage,node_leaguepages,node_csv,node_csvutil,node_gameview,node_gamecard,node_leagueutil toneAmber
class node_backend,node_authroute,node_publicroute,node_adminroute,node_security,node_securityjwt toneMint
class node_standings,node_storage,node_models,node_database,node_config toneRose
```

## Components

### Web application

- [App routing](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### League operations

- [League home](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/HomePage.tsx): `apps/web/src/pages/HomePage.tsx`
- [Games management](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/GamesPage.tsx): `apps/web/src/pages/GamesPage.tsx`
- [Team management](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/TeamsPage.tsx): `apps/web/src/pages/TeamsPage.tsx`
- [Player rosters](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/RosterPage.tsx): `apps/web/src/pages/RosterPage.tsx`
- [Standings view](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/pages/StandingsPage.tsx): `apps/web/src/pages/StandingsPage.tsx`
- [Content pages](https://github.com/mgomez1023/mens-league-mvp/tree/main/apps/web/src/pages): `apps/web/src/pages`
- [CSV import](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/components/CsvImportModal.tsx): `apps/web/src/components/CsvImportModal.tsx`
- [CSV processing](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/utils/csvImport.ts): `apps/web/src/utils/csvImport.ts`
- [Game details](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/components/GameDetailsDialog.tsx): `apps/web/src/components/GameDetailsDialog.tsx`
- [Public game card](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/components/PublicGameCard.tsx): `apps/web/src/components/PublicGameCard.tsx`
- [League formatting](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/web/src/utils/league.ts): `apps/web/src/utils/league.ts`

### API service

- [FastAPI application](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Authentication routes](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/auth.py): `apps/api/app/routers/auth.py`
- [Public routes](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/public.py): `apps/api/app/routers/public.py`
- [Admin routes](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/routers/admin.py): `apps/api/app/routers/admin.py`
- [Access control](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/deps.py): `apps/api/app/deps.py`
- [Token security](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/security.py): `apps/api/app/security.py`

### League data

- [Standings engine](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/standings.py): `apps/api/app/standings.py`
- [Image storage](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/storage.py): `apps/api/app/storage.py`
- [League models](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/models.py): `apps/api/app/models.py`
- [Database sessions](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/db.py): `apps/api/app/db.py`
- [Runtime settings](https://github.com/mgomez1023/mens-league-mvp/blob/main/apps/api/app/config.py): `apps/api/app/config.py`

### Other components

- **League user**

## Connections

- League user → App routing: uses
- App routing → League home: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Games management: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Team management: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Player rosters: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Standings view: routes to (evidence: `apps/web/src/App.tsx`)
- App routing → Content pages: routes to (evidence: `apps/web/src/App.tsx`)
- Games management → API client: requests data (evidence: `apps/web/src/pages/GamesPage.tsx`)
- CSV import → CSV processing: processes import (evidence: `apps/web/src/components/CsvImportModal.tsx`)
- Games management → CSV import: opens import (evidence: `apps/web/src/pages/GamesPage.tsx`)
- Games management → Game details: shows details (evidence: `apps/web/src/pages/GamesPage.tsx`)
- Game details → League formatting: formats game (evidence: `apps/web/src/components/GameDetailsDialog.tsx`)
- Public game card → League formatting: formats game (evidence: `apps/web/src/components/PublicGameCard.tsx`)
- API client → FastAPI application: HTTP requests (evidence: `README.md`)
- FastAPI application → Authentication routes: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Admin routes: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Public routes: registers routes (evidence: `apps/api/app/main.py`)
- FastAPI application → Standings engine: uses calculations (evidence: `apps/api/app/main.py`)
- FastAPI application → Image storage: serves uploads (evidence: `apps/api/app/main.py`)
- Authentication routes → Access control: validates access (evidence: `apps/api/app/routers/auth.py`)
- Admin routes → Access control: checks permissions (evidence: `apps/api/app/routers/admin.py`)
- Public routes → Standings engine: requests rankings (evidence: `apps/api/app/routers/public.py`)
- Admin routes → Standings engine: updates rankings (evidence: `apps/api/app/routers/admin.py`)
- Admin routes → Image storage: handles images (evidence: `apps/api/app/routers/admin.py`)
- Public routes → Image storage: resolves images (evidence: `apps/api/app/routers/public.py`)
- Standings engine → League models: reads league data (evidence: `apps/api/app/standings.py`)
- Authentication routes → League models: loads users (evidence: `apps/api/app/routers/auth.py`)
- Admin routes → League models: manages records (evidence: `apps/api/app/routers/admin.py`)
- Public routes → League models: reads records (evidence: `apps/api/app/routers/public.py`)
- League models → Database sessions: maps tables (evidence: `apps/api/app/models.py`)
- Database sessions → Runtime settings: gets settings (evidence: `apps/api/app/db.py`)
- Access control → Runtime settings: uses JWT settings (evidence: `apps/api/app/deps.py`)
- Authentication routes → Token security: issues tokens (evidence: `apps/api/app/routers/auth.py`)
