# jonnykeys/sports-psychic architecture

> Architecture diagram of the GitHub repository jonnykeys/sports-psychic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jonnykeys/sports-psychic
- Repository: https://github.com/jonnykeys/sports-psychic

## Overview

Sports Psychic is an NFL pick’em and forecasting platform with an offline-resilient PWA, live scoreboard ingestion, scoring and standings, league membership, and cloud persistence. The principal flow is forecasts and game state through temporal reconciliation and deterministic scoring into matchup and leaderboard views; authentication and league/pick-sheet persistence support the social workflow. The repository also contains the standalone OG League viewer. Connections among the newer client subsystems follow the README architecture; several implementation details and the top-level wiring are unsampled.

Main entry points: [`apps/og-league/app.js`](https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js) (Reactive State), [`src/engine/scoring.js`](https://github.com/jonnykeys/sports-psychic/blob/main/src/engine/scoring.js) (Scoring Engine), [`src/api/espn.js`](https://github.com/jonnykeys/sports-psychic/blob/main/src/api/espn.js) (ESPN Scoreboard), [`src/utils/teams.js`](https://github.com/jonnykeys/sports-psychic/blob/main/src/utils/teams.js) (Team Directory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and Views"]
  node_clientapp["PWA Client<br/>[app.js]"]
  node_state["Reactive State<br/>[app.js]"]
  node_cache[("Browser Cache<br/>[app.js]")]
  node_matchups["Matchup Views<br/>[matchups.js]"]
  node_standings["Standings Views<br/>[standings.js]"]
end

subgraph group_domain["Forecast Domain"]
  node_calendar["NFL Calendar<br/>[dates.js]"]
  node_teams["Team Directory<br/>[teams.js]"]
  node_auditor["Temporal Auditor<br/>[scoring.js]"]
  node_scoring["Scoring Engine<br/>[scoring.js]"]
end

subgraph group_integrations["External Integrations"]
  node_espn["ESPN Scoreboard<br/>[espn.js]"]
  node_espnservice["ESPN API"]
  node_google[("Google Sheets")]
end

subgraph group_persistence["Cloud Persistence"]
  node_auth["Authentication<br/>[supabase.js]"]
  node_league["League Service<br/>[supabase.js]"]
  node_picks["Pick Sheets<br/>[supabase.js]"]
  node_supabase["Supabase"]
  node_postgres[("PostgreSQL")]
end

node_player(("Player"))

node_player -->|"views"| node_clientapp
node_clientapp -.->|"syncs data"| node_google
node_espnservice -->|"supplies telemetry"| node_auditor
node_auditor -->|"audits weeks"| node_state
node_state -->|"provides predictions"| node_scoring
node_scoring -->|"scores forecasts"| node_matchups
node_scoring -->|"ranks players"| node_standings
node_state -->|"syncs snapshots"| node_cache
node_cache -->|"restores snapshots"| node_state
node_espn -.->|"requests scores"| node_espnservice
node_espn -->|"normalizes codes"| node_teams
node_player -.->|"authenticates"| node_auth
node_player -.->|"manages leagues"| node_league
node_player -.->|"saves picks"| node_picks
node_auth -.->|"uses auth"| node_supabase
node_league -.->|"queries memberships"| node_supabase
node_picks -.->|"persists sheets"| node_supabase
node_supabase -.->|"stores records"| node_postgres
node_calendar -.->|"provides week rules"| node_clientapp
node_teams -.->|"provides team data"| node_matchups

click node_clientapp "https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js"
click node_state "https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js"
click node_cache "https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js"
click node_matchups "https://github.com/jonnykeys/sports-psychic/blob/main/src/ui/matchups.js"
click node_standings "https://github.com/jonnykeys/sports-psychic/blob/main/src/ui/standings.js"
click node_calendar "https://github.com/jonnykeys/sports-psychic/blob/main/src/utils/dates.js"
click node_teams "https://github.com/jonnykeys/sports-psychic/blob/main/src/utils/teams.js"
click node_auditor "https://github.com/jonnykeys/sports-psychic/blob/main/src/engine/scoring.js"
click node_scoring "https://github.com/jonnykeys/sports-psychic/blob/main/src/engine/scoring.js"
click node_espn "https://github.com/jonnykeys/sports-psychic/blob/main/src/api/espn.js"
click node_auth "https://github.com/jonnykeys/sports-psychic/blob/main/src/services/supabase.js"
click node_league "https://github.com/jonnykeys/sports-psychic/blob/main/src/services/supabase.js"
click node_picks "https://github.com/jonnykeys/sports-psychic/blob/main/src/services/supabase.js"
click node_postgres "https://github.com/jonnykeys/sports-psychic/blob/main/database/supabase_schema.sql"

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_clientapp,node_state,node_cache,node_matchups,node_standings toneBlue
class node_calendar,node_teams,node_auditor,node_scoring toneAmber
class node_espn,node_espnservice,node_google toneMint
class node_auth,node_league,node_picks,node_supabase,node_postgres toneRose
class node_player toneIndigo
```

## Components

### Client and Views

- [PWA Client](https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js): `apps/og-league/app.js`
- [Reactive State](https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js): `apps/og-league/app.js`
- [Browser Cache](https://github.com/jonnykeys/sports-psychic/blob/main/apps/og-league/app.js): `apps/og-league/app.js`
- [Matchup Views](https://github.com/jonnykeys/sports-psychic/blob/main/src/ui/matchups.js): `src/ui/matchups.js`
- [Standings Views](https://github.com/jonnykeys/sports-psychic/blob/main/src/ui/standings.js): `src/ui/standings.js`

### Forecast Domain

- [NFL Calendar](https://github.com/jonnykeys/sports-psychic/blob/main/src/utils/dates.js): `src/utils/dates.js`
- [Team Directory](https://github.com/jonnykeys/sports-psychic/blob/main/src/utils/teams.js): `src/utils/teams.js`
- [Temporal Auditor](https://github.com/jonnykeys/sports-psychic/blob/main/src/engine/scoring.js): `src/engine/scoring.js`
- [Scoring Engine](https://github.com/jonnykeys/sports-psychic/blob/main/src/engine/scoring.js): `src/engine/scoring.js`

### External Integrations

- [ESPN Scoreboard](https://github.com/jonnykeys/sports-psychic/blob/main/src/api/espn.js): `src/api/espn.js`
- **ESPN API**
- **Google Sheets**

### Cloud Persistence

- [Authentication](https://github.com/jonnykeys/sports-psychic/blob/main/src/services/supabase.js): `src/services/supabase.js`
- [League Service](https://github.com/jonnykeys/sports-psychic/blob/main/src/services/supabase.js): `src/services/supabase.js`
- [Pick Sheets](https://github.com/jonnykeys/sports-psychic/blob/main/src/services/supabase.js): `src/services/supabase.js`
- **Supabase**
- [PostgreSQL](https://github.com/jonnykeys/sports-psychic/blob/main/database/supabase_schema.sql): `database/supabase_schema.sql`

### Other components

- **Player**

## Connections

- Player → PWA Client: views (evidence: `apps/og-league/app.js`)
- PWA Client → Google Sheets: syncs data (evidence: `apps/og-league/app.js`)
- ESPN API → Temporal Auditor: supplies telemetry (evidence: `README.md`)
- Temporal Auditor → Reactive State: audits weeks (evidence: `README.md`)
- Reactive State → Scoring Engine: provides predictions (evidence: `README.md`)
- Scoring Engine → Matchup Views: scores forecasts (evidence: `README.md`)
- Scoring Engine → Standings Views: ranks players (evidence: `README.md`)
- Reactive State → Browser Cache: syncs snapshots (evidence: `README.md`)
- Browser Cache → Reactive State: restores snapshots (evidence: `README.md`)
- ESPN Scoreboard → ESPN API: requests scores
- ESPN Scoreboard → Team Directory: normalizes codes (evidence: `src/api/espn.js`)
- Player → Authentication: authenticates (evidence: `README.md`)
- Player → League Service: manages leagues (evidence: `README.md`)
- Player → Pick Sheets: saves picks (evidence: `README.md`)
- Authentication → Supabase: uses auth (evidence: `README.md`)
- League Service → Supabase: queries memberships (evidence: `README.md`)
- Pick Sheets → Supabase: persists sheets (evidence: `README.md`)
- Supabase → PostgreSQL: stores records (evidence: `README.md`)
- NFL Calendar → PWA Client: provides week rules
- Team Directory → Matchup Views: provides team data