# dkj121/runner architecture

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

- Interactive diagram: https://gitdiagram.com/dkj121/runner
- Repository: https://github.com/dkj121/runner

## Overview

RUNNER is a running and running-group web app. Its main workflow captures a user’s GPS track, sends sequenced points and pause/resume/stop events to run APIs, then confirms and stores a calculated run for history and analysis. Playground membership, invitations, and leaderboards are a separate social branch. The graph focuses on these documented capabilities and sampled runtime paths; unsampled UI and API internals are represented at their exact enclosing paths, with no inferred links where wiring was not shown.

Main entry points: [`src/lib/gps-cache.ts`](https://github.com/dkj121/runner/blob/main/src/lib/gps-cache.ts) (Live run cache), [`src/app/api/runs/[runId]/route.ts`](https://github.com/dkj121/runner/blob/main/src/app/api/runs/%5BrunId%5D/route.ts) (Run detail API), [`src/lib/prisma.ts`](https://github.com/dkj121/runner/blob/main/src/lib/prisma.ts) (Database access), [`src/lib/create-route.ts`](https://github.com/dkj121/runner/blob/main/src/lib/create-route.ts) (Route wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run_client["Run tracking"]
  node_run_ui["Run screens<br/>[page.tsx]"]
  node_tracker["Run tracker<br/>[use-run-tracker.ts]"]
  node_gps["GPS tracking"]
  node_map["Map display<br/>[map-loader.tsx]"]
end

subgraph group_run_api["Run services"]
  node_run_api["Run APIs<br/>[route.ts]"]
  node_run_detail_api["Run detail API<br/>[route.ts]"]
  node_complete_api["Completion API<br/>[route.ts]"]
  node_run_wrapper["Route wrapper<br/>[create-route.ts]"]
end

subgraph group_run_domain["Run processing"]
  node_lifecycle["Run lifecycle<br/>[run-lifecycle.ts]"]
  node_gps_cache["Live run cache<br/>[gps-cache.ts]"]
  node_timeline["Timeline processing<br/>[run-timeline.ts]"]
  node_validation["Track validation"]
  node_track_calc["Track calculations<br/>[track-calc.ts]"]
  node_confirmed["Run confirmation<br/>[confirmed-run.ts]"]
  node_run_contract["Run data contract<br/>[run-contract.ts]"]
  node_run_query["Run queries<br/>[run-query.ts]"]
end

subgraph group_social["Running groups"]
  node_playground_ui["Group screens"]
  node_playground_api["Group APIs<br/>[route.ts]"]
  node_leaderboard_api["Leaderboards<br/>[route.ts]"]
end

subgraph group_platform["Identity and storage"]
  node_auth_ui["Sign-in screens<br/>[page.tsx]"]
  node_auth_client["Auth client<br/>[auth-client.ts]"]
  node_auth_server["Auth service<br/>[auth.ts]"]
  node_prisma[("Database access<br/>[prisma.ts]")]
  node_redis[("Redis cache<br/>[redis.ts]")]
end

node_runner(("Runner"))

node_runner -->|"uses"| node_run_ui
node_run_ui -.->|"starts tracking"| node_tracker
node_tracker -->|"uses GPS"| node_gps
node_tracker -->|"calculates track"| node_track_calc
node_tracker -->|"validates points"| node_validation
node_tracker -->|"uses events"| node_timeline
node_map -->|"groups segments"| node_timeline
node_map -->|"uses types"| node_run_contract
node_run_ui -.->|"renders map"| node_map
node_run_ui -.->|"requests runs"| node_run_api
node_run_api -->|"wraps handlers"| node_run_wrapper
node_run_api -->|"expires sessions"| node_lifecycle
node_run_api -->|"writes run records"| node_prisma
node_run_api -->|"creates session"| node_gps_cache
node_run_detail_api -->|"wraps handlers"| node_run_wrapper
node_run_detail_api -->|"enforces lifecycle"| node_lifecycle
node_run_detail_api -->|"reads records"| node_prisma
node_run_detail_api -->|"reads live data"| node_gps_cache
node_run_detail_api -->|"calculates duration"| node_timeline
node_run_detail_api -->|"calculates distance"| node_track_calc
node_complete_api -->|"wraps handler"| node_run_wrapper
node_complete_api -->|"calculates result"| node_confirmed
node_complete_api -->|"reads and clears"| node_gps_cache
node_complete_api -->|"stores completion"| node_prisma
node_confirmed -->|"calculates metrics"| node_track_calc
node_confirmed -->|"uses timeline"| node_timeline
node_confirmed -->|"uses types"| node_run_contract
node_gps_cache -->|"stores live data"| node_redis
node_gps_cache -->|"validates points"| node_validation
node_gps_cache -->|"validates events"| node_timeline
node_gps_cache -->|"uses types"| node_run_contract
node_lifecycle -->|"updates status"| node_prisma
node_lifecycle -->|"reads and clears"| node_gps_cache
node_lifecycle -.->|"used by routes"| node_run_wrapper
node_playground_ui -.->|"uses group APIs"| node_playground_api
node_playground_api -->|"reads and writes"| node_prisma
node_playground_api -->|"wraps handlers"| node_run_wrapper
node_leaderboard_api -->|"queries groups"| node_prisma
node_leaderboard_api -->|"filters runs"| node_run_query
node_auth_ui -.->|"uses auth"| node_auth_client
node_auth_client -.->|"auth requests"| node_auth_server
node_run_wrapper -->|"checks session"| node_auth_server
node_auth_server -->|"uses database"| node_prisma

click node_run_ui "https://github.com/dkj121/runner/blob/main/src/app/(dashboard)/run/page.tsx"
click node_tracker "https://github.com/dkj121/runner/blob/main/src/hooks/use-run-tracker.ts"
click node_gps "https://github.com/dkj121/runner/blob/main/src/hooks/use-gps-tracking.ts"
click node_map "https://github.com/dkj121/runner/blob/main/src/components/map-loader.tsx"
click node_run_api "https://github.com/dkj121/runner/blob/main/src/app/api/runs/route.ts"
click node_run_detail_api "https://github.com/dkj121/runner/blob/main/src/app/api/runs/%5BrunId%5D/route.ts"
click node_complete_api "https://github.com/dkj121/runner/blob/main/src/app/api/runs/%5BrunId%5D/complete/route.ts"
click node_run_wrapper "https://github.com/dkj121/runner/blob/main/src/lib/create-route.ts"
click node_lifecycle "https://github.com/dkj121/runner/blob/main/src/lib/run-lifecycle.ts"
click node_gps_cache "https://github.com/dkj121/runner/blob/main/src/lib/gps-cache.ts"
click node_timeline "https://github.com/dkj121/runner/blob/main/src/lib/run-timeline.ts"
click node_validation "https://github.com/dkj121/runner/blob/main/src/lib/track-point-validation.ts"
click node_track_calc "https://github.com/dkj121/runner/blob/main/src/lib/track-calc.ts"
click node_confirmed "https://github.com/dkj121/runner/blob/main/src/lib/confirmed-run.ts"
click node_run_contract "https://github.com/dkj121/runner/blob/main/src/lib/run-contract.ts"
click node_run_query "https://github.com/dkj121/runner/blob/main/src/lib/run-query.ts"
click node_playground_ui "https://github.com/dkj121/runner/tree/main/src/app/(dashboard)/playground"
click node_playground_api "https://github.com/dkj121/runner/blob/main/src/app/api/playgrounds/route.ts"
click node_leaderboard_api "https://github.com/dkj121/runner/blob/main/src/app/api/playgrounds/%5Bid%5D/leaderboard/route.ts"
click node_auth_ui "https://github.com/dkj121/runner/blob/main/src/app/(auth)/login/page.tsx"
click node_auth_client "https://github.com/dkj121/runner/blob/main/src/lib/auth-client.ts"
click node_auth_server "https://github.com/dkj121/runner/blob/main/src/lib/auth.ts"
click node_prisma "https://github.com/dkj121/runner/blob/main/src/lib/prisma.ts"
click node_redis "https://github.com/dkj121/runner/blob/main/src/lib/redis.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_run_ui,node_tracker,node_gps,node_map toneBlue
class node_run_api,node_run_detail_api,node_complete_api,node_run_wrapper toneAmber
class node_lifecycle,node_gps_cache,node_timeline,node_validation,node_track_calc,node_confirmed,node_run_contract,node_run_query toneMint
class node_playground_ui,node_playground_api,node_leaderboard_api toneRose
class node_auth_ui,node_auth_client,node_auth_server,node_prisma,node_redis,node_runner toneIndigo
```

## Components

### Run tracking

- [Run screens](https://github.com/dkj121/runner/blob/main/src/app/(dashboard)/run/page.tsx): `src/app/(dashboard)/run/page.tsx`
- [Run tracker](https://github.com/dkj121/runner/blob/main/src/hooks/use-run-tracker.ts): `src/hooks/use-run-tracker.ts`
- [GPS tracking](https://github.com/dkj121/runner/blob/main/src/hooks/use-gps-tracking.ts): `src/hooks/use-gps-tracking.ts`
- [Map display](https://github.com/dkj121/runner/blob/main/src/components/map-loader.tsx): `src/components/map-loader.tsx`

### Run services

- [Run APIs](https://github.com/dkj121/runner/blob/main/src/app/api/runs/route.ts): `src/app/api/runs/route.ts`
- [Run detail API](https://github.com/dkj121/runner/blob/main/src/app/api/runs/%5BrunId%5D/route.ts): `src/app/api/runs/[runId]/route.ts`
- [Completion API](https://github.com/dkj121/runner/blob/main/src/app/api/runs/%5BrunId%5D/complete/route.ts): `src/app/api/runs/[runId]/complete/route.ts`
- [Route wrapper](https://github.com/dkj121/runner/blob/main/src/lib/create-route.ts): `src/lib/create-route.ts`

### Run processing

- [Run lifecycle](https://github.com/dkj121/runner/blob/main/src/lib/run-lifecycle.ts): `src/lib/run-lifecycle.ts`
- [Live run cache](https://github.com/dkj121/runner/blob/main/src/lib/gps-cache.ts): `src/lib/gps-cache.ts`
- [Timeline processing](https://github.com/dkj121/runner/blob/main/src/lib/run-timeline.ts): `src/lib/run-timeline.ts`
- [Track validation](https://github.com/dkj121/runner/blob/main/src/lib/track-point-validation.ts): `src/lib/track-point-validation.ts`
- [Track calculations](https://github.com/dkj121/runner/blob/main/src/lib/track-calc.ts): `src/lib/track-calc.ts`
- [Run confirmation](https://github.com/dkj121/runner/blob/main/src/lib/confirmed-run.ts): `src/lib/confirmed-run.ts`
- [Run data contract](https://github.com/dkj121/runner/blob/main/src/lib/run-contract.ts): `src/lib/run-contract.ts`
- [Run queries](https://github.com/dkj121/runner/blob/main/src/lib/run-query.ts): `src/lib/run-query.ts`

### Running groups

- [Group screens](https://github.com/dkj121/runner/tree/main/src/app/(dashboard)/playground): `src/app/(dashboard)/playground`
- [Group APIs](https://github.com/dkj121/runner/blob/main/src/app/api/playgrounds/route.ts): `src/app/api/playgrounds/route.ts`
- [Leaderboards](https://github.com/dkj121/runner/blob/main/src/app/api/playgrounds/%5Bid%5D/leaderboard/route.ts): `src/app/api/playgrounds/[id]/leaderboard/route.ts`

### Identity and storage

- [Sign-in screens](https://github.com/dkj121/runner/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Auth client](https://github.com/dkj121/runner/blob/main/src/lib/auth-client.ts): `src/lib/auth-client.ts`
- [Auth service](https://github.com/dkj121/runner/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Database access](https://github.com/dkj121/runner/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Redis cache](https://github.com/dkj121/runner/blob/main/src/lib/redis.ts): `src/lib/redis.ts`

### Other components

- **Runner**

## Connections

- Runner → Run screens: uses
- Run screens → Run tracker: starts tracking
- Run tracker → GPS tracking: uses GPS (evidence: `src/hooks/use-run-tracker.ts`)
- Run tracker → Track calculations: calculates track (evidence: `src/hooks/use-run-tracker.ts`)
- Run tracker → Track validation: validates points (evidence: `src/hooks/use-run-tracker.ts`)
- Run tracker → Timeline processing: uses events (evidence: `src/hooks/use-run-tracker.ts`)
- Map display → Timeline processing: groups segments (evidence: `src/components/map-loader.tsx`)
- Map display → Run data contract: uses types (evidence: `src/components/map-loader.tsx`)
- Run screens → Map display: renders map
- Run screens → Run APIs: requests runs
- Run APIs → Route wrapper: wraps handlers (evidence: `src/app/api/runs/route.ts`)
- Run APIs → Run lifecycle: expires sessions (evidence: `src/app/api/runs/route.ts`)
- Run APIs → Database access: writes run records (evidence: `src/app/api/runs/route.ts`)
- Run APIs → Live run cache: creates session (evidence: `src/app/api/runs/route.ts`)
- Run detail API → Route wrapper: wraps handlers (evidence: `src/app/api/runs/[runId]/route.ts`)
- Run detail API → Run lifecycle: enforces lifecycle (evidence: `src/app/api/runs/[runId]/route.ts`)
- Run detail API → Database access: reads records (evidence: `src/app/api/runs/[runId]/route.ts`)
- Run detail API → Live run cache: reads live data (evidence: `src/app/api/runs/[runId]/route.ts`)
- Run detail API → Timeline processing: calculates duration (evidence: `src/app/api/runs/[runId]/route.ts`)
- Run detail API → Track calculations: calculates distance (evidence: `src/app/api/runs/[runId]/route.ts`)
- Completion API → Route wrapper: wraps handler (evidence: `src/app/api/runs/[runId]/complete/route.ts`)
- Completion API → Run confirmation: calculates result (evidence: `src/app/api/runs/[runId]/complete/route.ts`)
- Completion API → Live run cache: reads and clears (evidence: `src/app/api/runs/[runId]/complete/route.ts`)
- Completion API → Database access: stores completion (evidence: `src/app/api/runs/[runId]/complete/route.ts`)
- Run confirmation → Track calculations: calculates metrics (evidence: `src/lib/confirmed-run.ts`)
- Run confirmation → Timeline processing: uses timeline (evidence: `src/lib/confirmed-run.ts`)
- Run confirmation → Run data contract: uses types (evidence: `src/lib/confirmed-run.ts`)
- Live run cache → Redis cache: stores live data (evidence: `src/lib/gps-cache.ts`)
- Live run cache → Track validation: validates points (evidence: `src/lib/gps-cache.ts`)
- Live run cache → Timeline processing: validates events (evidence: `src/lib/gps-cache.ts`)
- Live run cache → Run data contract: uses types (evidence: `src/lib/gps-cache.ts`)
- Run lifecycle → Database access: updates status (evidence: `src/lib/run-lifecycle.ts`)
- Run lifecycle → Live run cache: reads and clears (evidence: `src/lib/run-lifecycle.ts`)
- Run lifecycle → Route wrapper: used by routes
- Group screens → Group APIs: uses group APIs
- Group APIs → Database access: reads and writes (evidence: `src/app/api/playgrounds/route.ts`)
- Group APIs → Route wrapper: wraps handlers (evidence: `src/app/api/playgrounds/route.ts`)
- Leaderboards → Database access: queries groups (evidence: `src/app/api/playgrounds/[id]/leaderboard/route.ts`)
- Leaderboards → Run queries: filters runs (evidence: `src/app/api/playgrounds/[id]/leaderboard/route.ts`)
- Sign-in screens → Auth client: uses auth
- Auth client → Auth service: auth requests
- Route wrapper → Auth service: checks session (evidence: `src/lib/create-route.ts`)
- Auth service → Database access: uses database (evidence: `src/lib/auth.ts`)
