# jpimen/topset architecture

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

- Interactive diagram: https://gitdiagram.com/jpimen/topset
- Repository: https://github.com/jpimen/topset

## Overview

Topset is a role-based powerlifting program builder and athlete training workspace. Coaches create and save programs, link athletes, and assign either live or snapshot plans; athletes review assigned training days, record workouts, and submit private check-ins. Authentication and role-based routing establish the workspace, while Supabase provides account and application data. The graph includes the calculation tools and rulebook as distinct product capabilities. Some feature pages are represented at their exact paths from the tree; their internal calls were not sampled, so uncertain links are omitted.

Main entry points: [`src/App.tsx`](https://github.com/jpimen/topset/blob/main/src/App.tsx) (Workspace routing), [`src/lib/supabase.ts`](https://github.com/jpimen/topset/blob/main/src/lib/supabase.ts) (Supabase client), [`src/lib/programs/repository.ts`](https://github.com/jpimen/topset/blob/main/src/lib/programs/repository.ts) (Program persistence), [`src/components/athlete/AthleteProgramPage.tsx`](https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteProgramPage.tsx) (Assigned program view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and workspace"]
  node_auth_page["Sign-in and signup<br/>[AuthPage.tsx]"]
  node_auth_state["Authentication state<br/>[AuthProvider.tsx]"]
  node_role_routes["Role-based routes<br/>[RouteGuards.tsx]"]
  node_app_routes["Workspace routing<br/>[App.tsx]"]
end

subgraph group_coaching["Coach programming"]
  node_coach_roster["Athlete linking<br/>[AthletesPage.tsx]"]
  node_coach_links["Coach-athlete links<br/>[coachAthletes.ts]"]
  node_program_list["Program management<br/>[ProgramsPage.tsx]"]
  node_program_builder["Program builder"]
  node_program_repository["Program persistence<br/>[repository.ts]"]
  node_program_layout["Program layout<br/>[layout.ts]"]
  node_assignments["Program assignments"]
end

subgraph group_athlete["Athlete training"]
  node_athlete_program["Assigned program view"]
  node_program_loader["Program loading and cache<br/>[programs.ts]"]
  node_workout_sessions["Workout history"]
  node_workout_logs["Workout log storage<br/>[logs.ts]"]
  node_checkins["Training-day check-ins"]
  node_checkin_storage["Check-in data<br/>[workoutCheckIns.ts]"]
  node_videos["Training videos"]
end

subgraph group_training_tools["Training tools"]
  node_calculators["Powerlifting calculators"]
  node_calc_engine["Calculation engine<br/>[shared.ts]"]
  node_rulebook["IPF rulebook"]
end

subgraph group_platform["Shared platform"]
  node_theme_toggle["Theme controls<br/>[ThemeToggle.tsx]"]
  node_theme_provider["Theme application<br/>[ThemeProvider.tsx]"]
  node_theme_preferences["Theme preferences<br/>[themePreference.ts]"]
  node_supabase["Supabase client<br/>[supabase.ts]"]
end

node_user(("Coach or athlete"))
node_remote_data[("Supabase services")]

node_user -->|"signs in"| node_auth_page
node_auth_page -->|"uses account state"| node_auth_state
node_auth_state -->|"authenticates and reads profiles"| node_supabase
node_app_routes -->|"provides auth"| node_auth_state
node_app_routes -->|"guards workspaces"| node_role_routes
node_role_routes -->|"checks role"| node_auth_state
node_app_routes -->|"routes to"| node_auth_page
node_app_routes -->|"routes to"| node_coach_roster
node_app_routes -->|"routes to"| node_program_list
node_app_routes -->|"routes to"| node_program_builder
node_app_routes -->|"routes to"| node_athlete_program
node_app_routes -->|"routes to"| node_videos
node_app_routes -->|"routes to"| node_calculators
node_app_routes -->|"routes to"| node_rulebook
node_coach_roster -->|"manages links"| node_coach_links
node_coach_links -->|"calls relationship APIs"| node_supabase
node_program_list -->|"loads and manages programs"| node_program_repository
node_program_list -->|"manages assignments"| node_assignments
node_program_builder -->|"loads and saves"| node_program_repository
node_program_builder -->|"queries active assignments"| node_assignments
node_program_repository -->|"normalizes layout"| node_program_layout
node_program_repository -->|"reads and writes programs"| node_supabase
node_assignments -->|"uses data client"| node_supabase
node_athlete_program -->|"loads assigned plans"| node_program_loader
node_program_loader -->|"loads live program"| node_program_repository
node_program_loader -->|"queries assignments"| node_supabase
node_athlete_program -->|"uses session provider"| node_workout_sessions
node_workout_sessions -->|"loads workout logs"| node_workout_logs
node_workout_logs -->|"reads and writes logs"| node_supabase
node_athlete_program -->|"renders check-in panel"| node_checkins
node_checkins -.->|"persists responses"| node_checkin_storage
node_videos -->|"uses data client"| node_supabase
node_calculators -->|"uses calculation engine"| node_calc_engine
node_theme_toggle -->|"changes appearance"| node_theme_provider
node_theme_provider -->|"reads and stores"| node_theme_preferences
node_theme_provider -->|"wraps application"| node_app_routes
node_supabase -->|"connects to"| node_remote_data

click node_auth_page "https://github.com/jpimen/topset/blob/main/src/components/AuthPage.tsx"
click node_auth_state "https://github.com/jpimen/topset/blob/main/src/auth/AuthProvider.tsx"
click node_role_routes "https://github.com/jpimen/topset/blob/main/src/auth/RouteGuards.tsx"
click node_app_routes "https://github.com/jpimen/topset/blob/main/src/App.tsx"
click node_coach_roster "https://github.com/jpimen/topset/blob/main/src/components/coach/AthletesPage.tsx"
click node_coach_links "https://github.com/jpimen/topset/blob/main/src/lib/coachAthletes.ts"
click node_program_list "https://github.com/jpimen/topset/blob/main/src/components/coach/ProgramsPage.tsx"
click node_program_builder "https://github.com/jpimen/topset/blob/main/src/components/programs/ProgramBuilderPage.tsx"
click node_program_repository "https://github.com/jpimen/topset/blob/main/src/lib/programs/repository.ts"
click node_program_layout "https://github.com/jpimen/topset/blob/main/src/lib/programs/layout.ts"
click node_assignments "https://github.com/jpimen/topset/blob/main/src/lib/programAssignments.ts"
click node_athlete_program "https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteProgramPage.tsx"
click node_program_loader "https://github.com/jpimen/topset/blob/main/src/lib/athlete/programs.ts"
click node_workout_sessions "https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteWorkoutSessionsProvider.tsx"
click node_workout_logs "https://github.com/jpimen/topset/blob/main/src/lib/athlete/logs.ts"
click node_checkins "https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteWorkoutCheckInPanel.tsx"
click node_checkin_storage "https://github.com/jpimen/topset/blob/main/src/lib/athlete/workoutCheckIns.ts"
click node_videos "https://github.com/jpimen/topset/blob/main/src/components/athlete/AthletePostVideoPage.tsx"
click node_calculators "https://github.com/jpimen/topset/blob/main/src/components/CalculatorsPage.tsx"
click node_calc_engine "https://github.com/jpimen/topset/blob/main/src/lib/engine/shared.ts"
click node_rulebook "https://github.com/jpimen/topset/blob/main/src/components/IPFRulebookPage.tsx"
click node_theme_toggle "https://github.com/jpimen/topset/blob/main/src/components/ThemeToggle.tsx"
click node_theme_provider "https://github.com/jpimen/topset/blob/main/src/theme/ThemeProvider.tsx"
click node_theme_preferences "https://github.com/jpimen/topset/blob/main/src/lib/themePreference.ts"
click node_supabase "https://github.com/jpimen/topset/blob/main/src/lib/supabase.ts"

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_auth_page,node_auth_state,node_role_routes,node_app_routes toneBlue
class node_coach_roster,node_coach_links,node_program_list,node_program_builder,node_program_repository,node_program_layout,node_assignments,node_remote_data toneAmber
class node_athlete_program,node_program_loader,node_workout_sessions,node_workout_logs,node_checkins,node_checkin_storage,node_videos toneMint
class node_calculators,node_calc_engine,node_rulebook toneRose
class node_theme_toggle,node_theme_provider,node_theme_preferences,node_supabase,node_user toneIndigo
```

## Components

### Access and workspace

- [Sign-in and signup](https://github.com/jpimen/topset/blob/main/src/components/AuthPage.tsx): `src/components/AuthPage.tsx`
- [Authentication state](https://github.com/jpimen/topset/blob/main/src/auth/AuthProvider.tsx): `src/auth/AuthProvider.tsx`
- [Role-based routes](https://github.com/jpimen/topset/blob/main/src/auth/RouteGuards.tsx): `src/auth/RouteGuards.tsx`
- [Workspace routing](https://github.com/jpimen/topset/blob/main/src/App.tsx): `src/App.tsx`

### Coach programming

- [Athlete linking](https://github.com/jpimen/topset/blob/main/src/components/coach/AthletesPage.tsx): `src/components/coach/AthletesPage.tsx`
- [Coach-athlete links](https://github.com/jpimen/topset/blob/main/src/lib/coachAthletes.ts): `src/lib/coachAthletes.ts`
- [Program management](https://github.com/jpimen/topset/blob/main/src/components/coach/ProgramsPage.tsx): `src/components/coach/ProgramsPage.tsx`
- [Program builder](https://github.com/jpimen/topset/blob/main/src/components/programs/ProgramBuilderPage.tsx): `src/components/programs/ProgramBuilderPage.tsx`
- [Program persistence](https://github.com/jpimen/topset/blob/main/src/lib/programs/repository.ts): `src/lib/programs/repository.ts`
- [Program layout](https://github.com/jpimen/topset/blob/main/src/lib/programs/layout.ts): `src/lib/programs/layout.ts`
- [Program assignments](https://github.com/jpimen/topset/blob/main/src/lib/programAssignments.ts): `src/lib/programAssignments.ts`

### Athlete training

- [Assigned program view](https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteProgramPage.tsx): `src/components/athlete/AthleteProgramPage.tsx`
- [Program loading and cache](https://github.com/jpimen/topset/blob/main/src/lib/athlete/programs.ts): `src/lib/athlete/programs.ts`
- [Workout history](https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteWorkoutSessionsProvider.tsx): `src/components/athlete/AthleteWorkoutSessionsProvider.tsx`
- [Workout log storage](https://github.com/jpimen/topset/blob/main/src/lib/athlete/logs.ts): `src/lib/athlete/logs.ts`
- [Training-day check-ins](https://github.com/jpimen/topset/blob/main/src/components/athlete/AthleteWorkoutCheckInPanel.tsx): `src/components/athlete/AthleteWorkoutCheckInPanel.tsx`
- [Check-in data](https://github.com/jpimen/topset/blob/main/src/lib/athlete/workoutCheckIns.ts): `src/lib/athlete/workoutCheckIns.ts`
- [Training videos](https://github.com/jpimen/topset/blob/main/src/components/athlete/AthletePostVideoPage.tsx): `src/components/athlete/AthletePostVideoPage.tsx`

### Training tools

- [Powerlifting calculators](https://github.com/jpimen/topset/blob/main/src/components/CalculatorsPage.tsx): `src/components/CalculatorsPage.tsx`
- [Calculation engine](https://github.com/jpimen/topset/blob/main/src/lib/engine/shared.ts): `src/lib/engine/shared.ts`
- [IPF rulebook](https://github.com/jpimen/topset/blob/main/src/components/IPFRulebookPage.tsx): `src/components/IPFRulebookPage.tsx`

### Shared platform

- [Theme controls](https://github.com/jpimen/topset/blob/main/src/components/ThemeToggle.tsx): `src/components/ThemeToggle.tsx`
- [Theme application](https://github.com/jpimen/topset/blob/main/src/theme/ThemeProvider.tsx): `src/theme/ThemeProvider.tsx`
- [Theme preferences](https://github.com/jpimen/topset/blob/main/src/lib/themePreference.ts): `src/lib/themePreference.ts`
- [Supabase client](https://github.com/jpimen/topset/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`

### Other components

- **Coach or athlete**
- **Supabase services**

## Connections

- Coach or athlete → Sign-in and signup: signs in
- Sign-in and signup → Authentication state: uses account state (evidence: `src/components/AuthPage.tsx`)
- Authentication state → Supabase client: authenticates and reads profiles (evidence: `src/auth/AuthProvider.tsx`)
- Workspace routing → Authentication state: provides auth (evidence: `src/App.tsx`)
- Workspace routing → Role-based routes: guards workspaces (evidence: `src/App.tsx`)
- Role-based routes → Authentication state: checks role (evidence: `src/auth/RouteGuards.tsx`)
- Workspace routing → Sign-in and signup: routes to (evidence: `src/App.tsx`)
- Workspace routing → Athlete linking: routes to (evidence: `src/App.tsx`)
- Workspace routing → Program management: routes to (evidence: `src/App.tsx`)
- Workspace routing → Program builder: routes to (evidence: `src/App.tsx`)
- Workspace routing → Assigned program view: routes to (evidence: `src/App.tsx`)
- Workspace routing → Training videos: routes to (evidence: `src/App.tsx`)
- Workspace routing → Powerlifting calculators: routes to (evidence: `src/App.tsx`)
- Workspace routing → IPF rulebook: routes to (evidence: `src/App.tsx`)
- Athlete linking → Coach-athlete links: manages links (evidence: `src/components/coach/AthletesPage.tsx`)
- Coach-athlete links → Supabase client: calls relationship APIs (evidence: `src/lib/coachAthletes.ts`)
- Program management → Program persistence: loads and manages programs (evidence: `src/components/coach/ProgramsPage.tsx`)
- Program management → Program assignments: manages assignments (evidence: `src/components/coach/ProgramsPage.tsx`)
- Program builder → Program persistence: loads and saves (evidence: `src/components/programs/ProgramBuilderPage.tsx`)
- Program builder → Program assignments: queries active assignments (evidence: `src/components/programs/ProgramBuilderPage.tsx`)
- Program persistence → Program layout: normalizes layout (evidence: `src/lib/programs/repository.ts`)
- Program persistence → Supabase client: reads and writes programs (evidence: `src/lib/programs/repository.ts`)
- Program assignments → Supabase client: uses data client (evidence: `src/lib/programAssignments.ts`)
- Assigned program view → Program loading and cache: loads assigned plans (evidence: `src/components/athlete/AthleteProgramPage.tsx`)
- Program loading and cache → Program persistence: loads live program (evidence: `src/lib/athlete/programs.ts`)
- Program loading and cache → Supabase client: queries assignments (evidence: `src/lib/athlete/programs.ts`)
- Assigned program view → Workout history: uses session provider (evidence: `src/components/athlete/AthleteProgramPage.tsx`)
- Workout history → Workout log storage: loads workout logs (evidence: `src/components/athlete/AthleteWorkoutSessionsProvider.tsx`)
- Workout log storage → Supabase client: reads and writes logs (evidence: `src/lib/athlete/logs.ts`)
- Assigned program view → Training-day check-ins: renders check-in panel (evidence: `src/components/athlete/AthleteProgramPage.tsx`)
- Training-day check-ins → Check-in data: persists responses
- Training videos → Supabase client: uses data client
- Powerlifting calculators → Calculation engine: uses calculation engine (evidence: `src/components/CalculatorsPage.tsx`)
- Theme controls → Theme application: changes appearance (evidence: `src/components/ThemeToggle.tsx`)
- Theme application → Theme preferences: reads and stores (evidence: `src/theme/ThemeProvider.tsx`)
- Theme application → Workspace routing: wraps application (evidence: `src/App.tsx`)
- Supabase client → Supabase services: connects to (evidence: `src/lib/supabase.ts`)
