# peterwb1/osrs-xp-tracker architecture

> Architecture diagram of the GitHub repository peterwb1/osrs-xp-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peterwb1/osrs-xp-tracker
- Repository: https://github.com/peterwb1/osrs-xp-tracker

## Overview

OSRS XP Tracker is a multi-user web app: users authenticate, register OSRS usernames, and view per-account skill snapshots, dashboard metrics, and skill history gathered from the official Hiscores. The documented flow includes initial validation/snapshotting, scheduled polling, and manual refresh. The graph connects sampled controller, polling, and persistence code; frontend route and chart capabilities are documented but their detailed wiring was not sampled, so uncertain internal frontend links are omitted.

Main entry points: [`web/app`](https://github.com/peterwb1/osrs-xp-tracker/tree/main/web/app) (Web app), [`api/OsrsTracker.Api/Controllers/AccountsController.cs`](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Controllers/AccountsController.cs) (Account endpoints), [`web/lib/api.ts`](https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/lib/api.ts) (API client), [`api/OsrsTracker.Api/Services/AccountPoller.cs`](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Services/AccountPoller.cs) (Account poller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Web app"]
  node_account_pages["Account views"]
  node_dashboard_ui["Dashboard and charts"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_auth_ui["Auth state<br/>[auth.tsx]"]
end

subgraph group_api["API workflows"]
  node_auth_controller["Auth endpoints<br/>[AuthController.cs]"]
  node_accounts_controller["Account endpoints"]
end

subgraph group_tracking["Hiscores tracking"]
  node_poll_service["Scheduled polling<br/>[PollingService.cs]"]
  node_account_poller["Account poller<br/>[AccountPoller.cs]"]
  node_hiscores_client["Hiscores client<br/>[HiscoresClient.cs]"]
  node_hiscores_parser["CSV parser<br/>[HiscoresParser.cs]"]
end

subgraph group_storage["Identity and data"]
  node_identity[("Identity users<br/>[Program.cs]")]
  node_account_data[("Tracking data<br/>[AppDbContext.cs]")]
end

node_user(("User"))
node_hiscores_service["Official Hiscores"]

node_user -->|"uses"| node_frontend
node_frontend -->|"navigates"| node_account_pages
node_account_pages -->|"renders"| node_dashboard_ui
node_frontend -->|"requests"| node_frontend_api
node_frontend -->|"authenticates"| node_auth_ui
node_auth_ui -->|"uses"| node_frontend_api
node_frontend_api -->|"calls"| node_auth_controller
node_frontend_api -->|"calls"| node_accounts_controller
node_auth_controller -->|"reads/writes"| node_identity
node_accounts_controller -->|"reads/writes"| node_account_data
node_accounts_controller -->|"validates username"| node_hiscores_client
node_accounts_controller -->|"manual refresh"| node_account_poller
node_poll_service -->|"finds due accounts"| node_account_data
node_poll_service -->|"dispatches polls"| node_account_poller
node_account_poller -->|"fetches stats"| node_hiscores_client
node_hiscores_client -->|"requests CSV"| node_hiscores_service
node_hiscores_client -->|"parses response"| node_hiscores_parser
node_account_poller -->|"stores snapshots"| node_account_data

click node_frontend "https://github.com/peterwb1/osrs-xp-tracker/tree/main/web/app"
click node_account_pages "https://github.com/peterwb1/osrs-xp-tracker/tree/main/web/app/accounts"
click node_dashboard_ui "https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/components/AccountDashboard.tsx"
click node_frontend_api "https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/lib/api.ts"
click node_auth_ui "https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/lib/auth.tsx"
click node_auth_controller "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Controllers/AuthController.cs"
click node_accounts_controller "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Controllers/AccountsController.cs"
click node_identity "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Program.cs"
click node_account_data "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Data/AppDbContext.cs"
click node_poll_service "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Services/PollingService.cs"
click node_account_poller "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Services/AccountPoller.cs"
click node_hiscores_client "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Hiscores/HiscoresClient.cs"
click node_hiscores_parser "https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Domain/Hiscores/HiscoresParser.cs"

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_frontend,node_account_pages,node_dashboard_ui,node_frontend_api,node_auth_ui,node_user toneBlue
class node_auth_controller,node_accounts_controller toneAmber
class node_poll_service,node_account_poller,node_hiscores_client,node_hiscores_parser toneMint
class node_identity,node_account_data toneRose
class node_hiscores_service toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/peterwb1/osrs-xp-tracker/tree/main/web/app): `web/app`
- [Account views](https://github.com/peterwb1/osrs-xp-tracker/tree/main/web/app/accounts): `web/app/accounts`
- [Dashboard and charts](https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/components/AccountDashboard.tsx): `web/components/AccountDashboard.tsx`
- [API client](https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/lib/api.ts): `web/lib/api.ts`
- [Auth state](https://github.com/peterwb1/osrs-xp-tracker/blob/main/web/lib/auth.tsx): `web/lib/auth.tsx`

### API workflows

- [Auth endpoints](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Controllers/AuthController.cs): `api/OsrsTracker.Api/Controllers/AuthController.cs`
- [Account endpoints](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Controllers/AccountsController.cs): `api/OsrsTracker.Api/Controllers/AccountsController.cs`

### Hiscores tracking

- [Scheduled polling](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Services/PollingService.cs): `api/OsrsTracker.Api/Services/PollingService.cs`
- [Account poller](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Services/AccountPoller.cs): `api/OsrsTracker.Api/Services/AccountPoller.cs`
- [Hiscores client](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Hiscores/HiscoresClient.cs): `api/OsrsTracker.Api/Hiscores/HiscoresClient.cs`
- [CSV parser](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Domain/Hiscores/HiscoresParser.cs): `api/OsrsTracker.Domain/Hiscores/HiscoresParser.cs`

### Identity and data

- [Identity users](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Program.cs): `api/OsrsTracker.Api/Program.cs`
- [Tracking data](https://github.com/peterwb1/osrs-xp-tracker/blob/main/api/OsrsTracker.Api/Data/AppDbContext.cs): `api/OsrsTracker.Api/Data/AppDbContext.cs`

### Other components

- **User**
- **Official Hiscores**

## Connections

- User → Web app: uses
- Web app → Account views: navigates
- Account views → Dashboard and charts: renders
- Web app → API client: requests
- Web app → Auth state: authenticates
- Auth state → API client: uses
- API client → Auth endpoints: calls
- API client → Account endpoints: calls
- Auth endpoints → Identity users: reads/writes
- Account endpoints → Tracking data: reads/writes
- Account endpoints → Hiscores client: validates username
- Account endpoints → Account poller: manual refresh
- Scheduled polling → Tracking data: finds due accounts
- Scheduled polling → Account poller: dispatches polls
- Account poller → Hiscores client: fetches stats
- Hiscores client → Official Hiscores: requests CSV
- Hiscores client → CSV parser: parses response
- Account poller → Tracking data: stores snapshots