# pppp575/halfway architecture

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

- Interactive diagram: https://gitdiagram.com/pppp575/halfway
- Repository: https://github.com/pppp575/halfway

## Overview

Halfway is a daily geography game: players choose the great-circle halfway point for five city-pair rounds, then see the route and score. The browser game coordinates daily or practice puzzles, map interaction, scoring, saved progress, and optional online results. Its documented capabilities also include archives, hard mode, achievements, sharing, daily and all-time leaderboards, and private leagues. The main flow and several dependencies are visible in excerpts and the source index; unsampled feature wiring is shown only where documented or explicitly referenced.

Main entry points: [`src/game.js`](https://github.com/pppp575/halfway/blob/main/src/game.js) (Game coordinator), [`src/lib/puzzles.js`](https://github.com/pppp575/halfway/blob/main/src/lib/puzzles.js) (Puzzle generation), [`src/ui/map.js`](https://github.com/pppp575/halfway/blob/main/src/ui/map.js) (Interactive map), [`src/services/backend.js`](https://github.com/pppp575/halfway/blob/main/src/services/backend.js) (Backend client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Game play"]
  node_entry["App entry<br/>[main.js]"]
  node_game["Game coordinator<br/>[game.js]"]
end

subgraph group_domain["Puzzle domain"]
  node_cities["City dataset<br/>[cities.js]"]
  node_schedule["Daily schedule<br/>[schedule.json]"]
  node_puzzles["Puzzle generation<br/>[puzzles.js]"]
  node_dates["Date and archive rules<br/>[dates.js]"]
  node_geo["Geographic calculations<br/>[geo.js]"]
  node_random["Deterministic random<br/>[random.js]"]
  node_constants["Game constants<br/>[constants.js]"]
  node_scoring["Scoring<br/>[scoring.js]"]
  node_achievements["Achievements<br/>[achievements.js]"]
  node_callsigns["Player callsigns<br/>[callsigns.js]"]
end

subgraph group_presentation["Interface"]
  node_map["Interactive map<br/>[map.js]"]
  node_flaps["Scoreboard flaps<br/>[flaps.js]"]
  node_board["Leaderboard and leagues UI<br/>[board.js]"]
  node_share["Share card<br/>[shareCard.js]"]
end

subgraph group_services["Persistence and services"]
  node_storage[("Local save store<br/>[storage.js]")]
  node_backend["Backend client<br/>[backend.js]"]
  node_ads["Ad integration<br/>[ads.js]"]
end

node_player(("Player"))
node_supabase[("Supabase service")]

node_player -->|"opens game"| node_entry
node_entry -->|"starts"| node_game
node_game -->|"builds rounds"| node_puzzles
node_game -->|"uses city data"| node_cities
node_game -->|"reads schedule"| node_schedule
node_game -->|"resolves game day"| node_dates
node_puzzles -->|"selects pairs"| node_cities
node_puzzles -->|"checks schedule day"| node_dates
node_puzzles -->|"filters routes"| node_geo
node_puzzles -->|"seeds generation"| node_random
node_puzzles -->|"uses round count"| node_constants
node_game -->|"runs map rounds"| node_map
node_player -->|"places midpoint"| node_map
node_map -->|"measures error"| node_geo
node_game -->|"scores results"| node_scoring
node_game -->|"saves progress"| node_storage
node_game -->|"checks badges"| node_achievements
node_game -->|"validates identity"| node_callsigns
node_game -.->|"updates display"| node_flaps
node_game -->|"opens standings"| node_board
node_board -->|"requests standings"| node_backend
node_game -->|"submits rounds"| node_backend
node_backend -->|"calls RPCs"| node_supabase
node_game -->|"creates share image"| node_share
node_game -->|"uses ad service"| node_ads

click node_entry "https://github.com/pppp575/halfway/blob/main/src/main.js"
click node_game "https://github.com/pppp575/halfway/blob/main/src/game.js"
click node_cities "https://github.com/pppp575/halfway/blob/main/src/data/cities.js"
click node_schedule "https://github.com/pppp575/halfway/blob/main/src/data/schedule.json"
click node_puzzles "https://github.com/pppp575/halfway/blob/main/src/lib/puzzles.js"
click node_dates "https://github.com/pppp575/halfway/blob/main/src/lib/dates.js"
click node_geo "https://github.com/pppp575/halfway/blob/main/src/lib/geo.js"
click node_random "https://github.com/pppp575/halfway/blob/main/src/lib/random.js"
click node_constants "https://github.com/pppp575/halfway/blob/main/src/lib/constants.js"
click node_map "https://github.com/pppp575/halfway/blob/main/src/ui/map.js"
click node_flaps "https://github.com/pppp575/halfway/blob/main/src/ui/flaps.js"
click node_board "https://github.com/pppp575/halfway/blob/main/src/ui/board.js"
click node_share "https://github.com/pppp575/halfway/blob/main/src/ui/shareCard.js"
click node_scoring "https://github.com/pppp575/halfway/blob/main/src/lib/scoring.js"
click node_achievements "https://github.com/pppp575/halfway/blob/main/src/lib/achievements.js"
click node_callsigns "https://github.com/pppp575/halfway/blob/main/src/lib/callsigns.js"
click node_storage "https://github.com/pppp575/halfway/blob/main/src/lib/storage.js"
click node_backend "https://github.com/pppp575/halfway/blob/main/src/services/backend.js"
click node_ads "https://github.com/pppp575/halfway/blob/main/src/services/ads.js"

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_entry,node_game toneBlue
class node_cities,node_schedule,node_puzzles,node_dates,node_geo,node_random,node_constants,node_scoring,node_achievements,node_callsigns,node_supabase toneAmber
class node_map,node_flaps,node_board,node_share toneMint
class node_storage,node_backend,node_ads toneRose
class node_player toneIndigo
```

## Components

### Game play

- [App entry](https://github.com/pppp575/halfway/blob/main/src/main.js): `src/main.js`
- [Game coordinator](https://github.com/pppp575/halfway/blob/main/src/game.js): `src/game.js`

### Puzzle domain

- [City dataset](https://github.com/pppp575/halfway/blob/main/src/data/cities.js): `src/data/cities.js`
- [Daily schedule](https://github.com/pppp575/halfway/blob/main/src/data/schedule.json): `src/data/schedule.json`
- [Puzzle generation](https://github.com/pppp575/halfway/blob/main/src/lib/puzzles.js): `src/lib/puzzles.js`
- [Date and archive rules](https://github.com/pppp575/halfway/blob/main/src/lib/dates.js): `src/lib/dates.js`
- [Geographic calculations](https://github.com/pppp575/halfway/blob/main/src/lib/geo.js): `src/lib/geo.js`
- [Deterministic random](https://github.com/pppp575/halfway/blob/main/src/lib/random.js): `src/lib/random.js`
- [Game constants](https://github.com/pppp575/halfway/blob/main/src/lib/constants.js): `src/lib/constants.js`
- [Scoring](https://github.com/pppp575/halfway/blob/main/src/lib/scoring.js): `src/lib/scoring.js`
- [Achievements](https://github.com/pppp575/halfway/blob/main/src/lib/achievements.js): `src/lib/achievements.js`
- [Player callsigns](https://github.com/pppp575/halfway/blob/main/src/lib/callsigns.js): `src/lib/callsigns.js`

### Interface

- [Interactive map](https://github.com/pppp575/halfway/blob/main/src/ui/map.js): `src/ui/map.js`
- [Scoreboard flaps](https://github.com/pppp575/halfway/blob/main/src/ui/flaps.js): `src/ui/flaps.js`
- [Leaderboard and leagues UI](https://github.com/pppp575/halfway/blob/main/src/ui/board.js): `src/ui/board.js`
- [Share card](https://github.com/pppp575/halfway/blob/main/src/ui/shareCard.js): `src/ui/shareCard.js`

### Persistence and services

- [Local save store](https://github.com/pppp575/halfway/blob/main/src/lib/storage.js): `src/lib/storage.js`
- [Backend client](https://github.com/pppp575/halfway/blob/main/src/services/backend.js): `src/services/backend.js`
- [Ad integration](https://github.com/pppp575/halfway/blob/main/src/services/ads.js): `src/services/ads.js`

### Other components

- **Player**
- **Supabase service**

## Connections

- Player → App entry: opens game (evidence: `README.md`)
- App entry → Game coordinator: starts (evidence: `src/main.js`)
- Game coordinator → Puzzle generation: builds rounds (evidence: `src/game.js`)
- Game coordinator → City dataset: uses city data (evidence: `src/game.js`)
- Game coordinator → Daily schedule: reads schedule (evidence: `src/game.js`)
- Game coordinator → Date and archive rules: resolves game day (evidence: `src/game.js`)
- Puzzle generation → City dataset: selects pairs (evidence: `src/lib/puzzles.js`)
- Puzzle generation → Date and archive rules: checks schedule day (evidence: `src/lib/puzzles.js`)
- Puzzle generation → Geographic calculations: filters routes (evidence: `src/lib/puzzles.js`)
- Puzzle generation → Deterministic random: seeds generation (evidence: `src/lib/puzzles.js`)
- Puzzle generation → Game constants: uses round count (evidence: `src/lib/puzzles.js`)
- Game coordinator → Interactive map: runs map rounds (evidence: `src/game.js`)
- Player → Interactive map: places midpoint (evidence: `src/ui/map.js`)
- Interactive map → Geographic calculations: measures error (evidence: `src/ui/map.js`)
- Game coordinator → Scoring: scores results (evidence: `src/game.js`)
- Game coordinator → Local save store: saves progress (evidence: `src/game.js`)
- Game coordinator → Achievements: checks badges (evidence: `src/game.js`)
- Game coordinator → Player callsigns: validates identity (evidence: `src/game.js`)
- Game coordinator → Scoreboard flaps: updates display (evidence: `src/game.js`)
- Game coordinator → Leaderboard and leagues UI: opens standings (evidence: `src/game.js`)
- Leaderboard and leagues UI → Backend client: requests standings (evidence: `src/ui/board.js`)
- Game coordinator → Backend client: submits rounds (evidence: `src/game.js`)
- Backend client → Supabase service: calls RPCs (evidence: `src/services/backend.js`)
- Game coordinator → Share card: creates share image (evidence: `src/game.js`)
- Game coordinator → Ad integration: uses ad service (evidence: `src/game.js`)