# r1demachine/endurance-fantasy-league architecture

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

- Interactive diagram: https://gitdiagram.com/r1demachine/endurance-fantasy-league
- Repository: https://github.com/r1demachine/endurance-fantasy-league

## Overview

Endurance Fantasy League turns athletes’ training and wellness data into XP, levels, and social competition. The main workflow is account access, connecting an Intervals.icu account, syncing training data, calculating progression, then viewing it in the dashboard; friends and live notifications form a parallel social branch. Backend call relationships are grounded in the excerpts and SOURCE INDEX. Frontend-to-API wiring was not shown, so those links are marked unverified.

Main entry points: [`backend/app/main.py`](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/routers/sync.py`](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/sync.py) (Training sync and profile), [`backend/app/models.py`](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/models.py) (Domain records), [`backend/app/dependencies.py`](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/dependencies.py) (User authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Athlete app"]
  node_login["Login and registration<br/>[page.tsx]"]
  node_dashboard["Training dashboard<br/>[page.tsx]"]
  node_activity_card["Activity details<br/>[ActivityCard.tsx]"]
  node_connect_sources["Connect sources<br/>[ConnectSources.tsx]"]
  node_profile["Athlete profile<br/>[page.tsx]"]
  node_social_hub["Friends hub<br/>[SocialHub.tsx]"]
  node_notification_bell["Notification bell"]
  node_auth_guard["Route guard<br/>[AuthGuard.tsx]"]
  node_api_cache["API cache<br/>[apiCache.ts]"]
end

subgraph group_api["API and identity"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Account endpoints<br/>[auth.py]"]
  node_auth_security["Token and secrets<br/>[auth.py]"]
  node_auth_dependencies["User authentication<br/>[dependencies.py]"]
  node_config["Application settings<br/>[config.py]"]
  node_data_models["Domain records<br/>[models.py]"]
  node_database[("Relational database<br/>[database.py]")]
  node_admin_routes["Admin endpoints<br/>[admin.py]"]
end

subgraph group_training["Training progression"]
  node_sync_routes["Training sync and profile<br/>[sync.py]"]
  node_intervals_client["Intervals.icu client<br/>[intervals.py]"]
  node_xp_service["XP and levels<br/>[xp.py]"]
  node_intervals_key["Connect API key<br/>[intervals_key.py]"]
end

subgraph group_social["Social features"]
  node_friends_routes["Friend requests<br/>[friends.py]"]
  node_notifications_routes["Notification endpoints<br/>[notifications.py]"]
  node_notification_service["Notification delivery<br/>[notifications.py]"]
  node_broker["Live event broker<br/>[broker.py]"]
end

node_athlete(("Athlete"))
node_intervals_service["Intervals.icu"]

node_athlete -.->|"signs in"| node_login
node_athlete -.->|"views progress"| node_dashboard
node_athlete -.->|"views profile"| node_profile
node_athlete -.->|"competes socially"| node_social_hub
node_dashboard -.->|"requests training data"| node_sync_routes
node_connect_sources -.->|"sets API key"| node_intervals_key
node_social_hub -.->|"uses friends API"| node_friends_routes
node_notification_bell -.->|"uses notification API"| node_notifications_routes
node_api_app -->|"registers routes"| node_sync_routes
node_api_app -->|"registers routes"| node_auth_routes
node_api_app -->|"registers routes"| node_intervals_key
node_api_app -->|"registers routes"| node_friends_routes
node_api_app -->|"registers routes"| node_notifications_routes
node_api_app -->|"registers routes"| node_admin_routes
node_api_app -->|"creates schema"| node_database
node_api_app -->|"initializes"| node_broker
node_database -->|"loads settings"| node_config
node_data_models -->|"uses base"| node_database
node_auth_dependencies -->|"gets session"| node_database
node_auth_dependencies -->|"loads user"| node_data_models
node_auth_dependencies -->|"decodes token"| node_auth_security
node_auth_routes -->|"queries users"| node_data_models
node_auth_routes -->|"hashes and issues tokens"| node_auth_security
node_auth_routes -->|"guards current user"| node_auth_dependencies
node_sync_routes -->|"requires user"| node_auth_dependencies
node_sync_routes -->|"reads and writes records"| node_data_models
node_sync_routes -->|"recalculates progression"| node_xp_service
node_sync_routes -->|"fetches training data"| node_intervals_client
node_intervals_client -->|"requests activity and wellness data"| node_intervals_service
node_intervals_key -->|"validates credentials"| node_intervals_client
node_intervals_key -->|"encrypts API key"| node_auth_security
node_friends_routes -->|"queries friendships"| node_data_models
node_friends_routes -->|"notifies accepted friend"| node_notification_service
node_notification_service -->|"stores notification"| node_data_models
node_notification_service -->|"publishes event"| node_broker
node_notifications_routes -->|"subscribes to events"| node_broker

click node_login "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/app/login/page.tsx"
click node_dashboard "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/app/dashboard/page.tsx"
click node_activity_card "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/ActivityCard.tsx"
click node_connect_sources "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/ConnectSources.tsx"
click node_profile "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/app/profile/page.tsx"
click node_social_hub "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/SocialHub.tsx"
click node_notification_bell "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/NotificationBell.tsx"
click node_auth_guard "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/AuthGuard.tsx"
click node_api_cache "https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/lib/apiCache.ts"
click node_api_app "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/auth.py"
click node_auth_security "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/auth.py"
click node_auth_dependencies "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/dependencies.py"
click node_config "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/config.py"
click node_data_models "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/models.py"
click node_database "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/database.py"
click node_sync_routes "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/sync.py"
click node_intervals_client "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/services/intervals.py"
click node_xp_service "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/services/xp.py"
click node_intervals_key "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/intervals_key.py"
click node_friends_routes "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/friends.py"
click node_notifications_routes "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/notifications.py"
click node_notification_service "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/services/notifications.py"
click node_broker "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/broker.py"
click node_admin_routes "https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/admin.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_login,node_dashboard,node_activity_card,node_connect_sources,node_profile,node_social_hub,node_notification_bell,node_auth_guard,node_api_cache toneBlue
class node_api_app,node_auth_routes,node_auth_security,node_auth_dependencies,node_config,node_data_models,node_database,node_admin_routes toneAmber
class node_sync_routes,node_intervals_client,node_xp_service,node_intervals_key toneMint
class node_friends_routes,node_notifications_routes,node_notification_service,node_broker toneRose
class node_athlete,node_intervals_service toneIndigo
```

## Components

### Athlete app

- [Login and registration](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Training dashboard](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/app/dashboard/page.tsx): `frontend/src/app/dashboard/page.tsx`
- [Activity details](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/ActivityCard.tsx): `frontend/src/components/ActivityCard.tsx`
- [Connect sources](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/ConnectSources.tsx): `frontend/src/components/ConnectSources.tsx`
- [Athlete profile](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/app/profile/page.tsx): `frontend/src/app/profile/page.tsx`
- [Friends hub](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/SocialHub.tsx): `frontend/src/components/SocialHub.tsx`
- [Notification bell](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/NotificationBell.tsx): `frontend/src/components/NotificationBell.tsx`
- [Route guard](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/components/AuthGuard.tsx): `frontend/src/components/AuthGuard.tsx`
- [API cache](https://github.com/r1demachine/endurance-fantasy-league/blob/main/frontend/src/lib/apiCache.ts): `frontend/src/lib/apiCache.ts`

### API and identity

- [FastAPI application](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/main.py): `backend/app/main.py`
- [Account endpoints](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Token and secrets](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [User authentication](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`
- [Application settings](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/config.py): `backend/app/config.py`
- [Domain records](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/models.py): `backend/app/models.py`
- [Relational database](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/database.py): `backend/app/database.py`
- [Admin endpoints](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`

### Training progression

- [Training sync and profile](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/sync.py): `backend/app/routers/sync.py`
- [Intervals.icu client](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/services/intervals.py): `backend/app/services/intervals.py`
- [XP and levels](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/services/xp.py): `backend/app/services/xp.py`
- [Connect API key](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/intervals_key.py): `backend/app/routers/intervals_key.py`

### Social features

- [Friend requests](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/friends.py): `backend/app/routers/friends.py`
- [Notification endpoints](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/routers/notifications.py): `backend/app/routers/notifications.py`
- [Notification delivery](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/services/notifications.py): `backend/app/services/notifications.py`
- [Live event broker](https://github.com/r1demachine/endurance-fantasy-league/blob/main/backend/app/broker.py): `backend/app/broker.py`

### Other components

- **Athlete**
- **Intervals.icu**

## Connections

- Athlete → Login and registration: signs in
- Athlete → Training dashboard: views progress
- Athlete → Athlete profile: views profile
- Athlete → Friends hub: competes socially
- Training dashboard → Training sync and profile: requests training data
- Connect sources → Connect API key: sets API key
- Friends hub → Friend requests: uses friends API
- Notification bell → Notification endpoints: uses notification API
- FastAPI application → Training sync and profile: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Account endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Connect API key: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Friend requests: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Notification endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Admin endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Relational database: creates schema (evidence: `backend/app/main.py`)
- FastAPI application → Live event broker: initializes (evidence: `backend/app/main.py`)
- Relational database → Application settings: loads settings (evidence: `backend/app/database.py`)
- Domain records → Relational database: uses base (evidence: `backend/app/models.py`)
- User authentication → Relational database: gets session (evidence: `backend/app/dependencies.py`)
- User authentication → Domain records: loads user (evidence: `backend/app/dependencies.py`)
- User authentication → Token and secrets: decodes token (evidence: `backend/app/dependencies.py`)
- Account endpoints → Domain records: queries users (evidence: `backend/app/routers/auth.py`)
- Account endpoints → Token and secrets: hashes and issues tokens (evidence: `backend/app/routers/auth.py`)
- Account endpoints → User authentication: guards current user (evidence: `backend/app/routers/auth.py`)
- Training sync and profile → User authentication: requires user (evidence: `backend/app/routers/sync.py`)
- Training sync and profile → Domain records: reads and writes records (evidence: `backend/app/routers/sync.py`)
- Training sync and profile → XP and levels: recalculates progression (evidence: `backend/app/routers/sync.py`)
- Training sync and profile → Intervals.icu client: fetches training data (evidence: `backend/app/routers/sync.py`)
- Intervals.icu client → Intervals.icu: requests activity and wellness data (evidence: `backend/app/services/intervals.py`)
- Connect API key → Intervals.icu client: validates credentials (evidence: `backend/app/routers/intervals_key.py`)
- Connect API key → Token and secrets: encrypts API key (evidence: `backend/app/routers/intervals_key.py`)
- Friend requests → Domain records: queries friendships (evidence: `backend/app/routers/friends.py`)
- Friend requests → Notification delivery: notifies accepted friend (evidence: `backend/app/routers/friends.py`)
- Notification delivery → Domain records: stores notification (evidence: `backend/app/services/notifications.py`)
- Notification delivery → Live event broker: publishes event (evidence: `backend/app/services/notifications.py`)
- Notification endpoints → Live event broker: subscribes to events (evidence: `backend/app/routers/notifications.py`)
