# therealpaulplay/openguessr architecture

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

- Interactive diagram: https://gitdiagram.com/therealpaulplay/openguessr
- Repository: https://github.com/therealpaulplay/openguessr

## Overview

OpenGuessr is a geography-guessing game and web application. A player enters through the game menu, chooses a map or mode, plays rounds using Street View locations, and sees a result; the README identifies a separate location-generation server and Google Maps Street View. The repository also includes multiplayer, community maps, competitions, accounts, and a shop. The graph preserves these documented capabilities, but several links are necessarily high-level: sampled source does not expose the gameplay route’s full runtime wiring or backend calls.

Main entry points: [`src/lib/components/MapPage.svelte`](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/MapPage.svelte) (Map page), [`src/lib/components/MainMenu.svelte`](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/MainMenu.svelte) (Game menu), [`src/lib/logic/multiplayerLogic.js`](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/multiplayerLogic.js) (Multiplayer runtime), [`src/routes/(game)/+page.svelte`](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/%2Bpage.svelte) (Game route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and navigation"]
  node_menu["Game menu<br/>[MainMenu.svelte]"]
  node_game_route["Game route<br/>[+page.svelte]"]
  node_game_layout["Game layout<br/>[+layout.svelte]"]
end

subgraph group_gameplay["Guessing gameplay"]
  node_map_page["Map page<br/>[MapPage.svelte]"]
  node_map_view["Map display<br/>[Map.svelte]"]
  node_panorama["Street View<br/>[Panorama.svelte]"]
  node_location_gen["Location generation"]
  node_result["Round results"]
  node_result_logic["Result calculations"]
end

subgraph group_multiplayer["Multiplayer"]
  node_multiplayer_route["Multiplayer pages<br/>[+page.svelte]"]
  node_multiplayer_logic["Multiplayer runtime"]
  node_matchmaking["Matchmaking"]
  node_multiplayer_state["Match state"]
end

subgraph group_community["Maps and competitions"]
  node_maps_route["Map browsing<br/>[+page.svelte]"]
  node_map_creation["Map creation<br/>[+page.svelte]"]
  node_competitions["Competitions<br/>[+page.svelte]"]
end

subgraph group_accounts["Accounts and commerce"]
  node_account["Account state<br/>[accountStore.js]"]
  node_signup["Signup flow<br/>[+page.svelte]"]
  node_shop["Shop<br/>[+page.svelte]"]
  node_shop_logic["Purchase operations<br/>[shopHelper.js]"]
end

node_player(("Player"))
node_account_service["Account backend"]
node_maps_service["Location server"]
node_google_maps["Google Maps"]
node_playsocket["PlaySocket"]

node_player -.->|"opens"| node_menu
node_menu -.->|"starts game"| node_game_route
node_game_route -.->|"renders"| node_map_page
node_map_page -.->|"displays map"| node_map_view
node_map_page -.->|"shows panorama"| node_panorama
node_maps_service -.->|"provides locations"| node_location_gen
node_location_gen -.->|"supplies locations"| node_map_page
node_google_maps -.->|"powers Street View"| node_panorama
node_map_page -.->|"shows round result"| node_result
node_result -.->|"uses scoring"| node_result_logic
node_player -.->|"opens multiplayer"| node_multiplayer_route
node_multiplayer_route -.->|"runs matches"| node_multiplayer_logic
node_multiplayer_logic -.->|"uses matchmaking"| node_matchmaking
node_multiplayer_logic -.->|"updates state"| node_multiplayer_state
node_playsocket -.->|"supports multiplayer"| node_multiplayer_logic
node_player -.->|"browses maps"| node_maps_route
node_player -.->|"creates maps"| node_map_creation
node_player -.->|"joins competitions"| node_competitions
node_menu -->|"reads login state"| node_account
node_menu -->|"prompts signup"| node_signup
node_player -.->|"browses shop"| node_shop
node_shop -.->|"handles purchases"| node_shop_logic
node_shop_logic -->|"requests purchases"| node_account_service
node_signup -.->|"authenticates"| node_account_service
node_game_route -.->|"uses layout"| node_game_layout

click node_menu "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/MainMenu.svelte"
click node_game_route "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/%2Bpage.svelte"
click node_game_layout "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/%2Blayout.svelte"
click node_map_page "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/MapPage.svelte"
click node_map_view "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/Map.svelte"
click node_panorama "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/Panorama.svelte"
click node_result "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/ResultScreen.svelte"
click node_result_logic "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/resultScoreLogic.js"
click node_multiplayer_route "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/multiplayer/%2Bpage.svelte"
click node_multiplayer_logic "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/multiplayerLogic.js"
click node_matchmaking "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/matchmakingLogic.js"
click node_multiplayer_state "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/stores/context-specific/multiplayerStore.js"
click node_maps_route "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/maps/%2Bpage.svelte"
click node_map_creation "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/maps/create/%2Bpage.svelte"
click node_competitions "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/competitions/%2Bpage.svelte"
click node_account "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/stores/accountStore.js"
click node_signup "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(other)/signup/%2Bpage.svelte"
click node_shop "https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/shop/%2Bpage.svelte"
click node_shop_logic "https://github.com/therealpaulplay/openguessr/blob/main/src/lib/utils/shopHelper.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_menu,node_game_route,node_game_layout toneBlue
class node_map_page,node_map_view,node_panorama,node_location_gen,node_result,node_result_logic toneAmber
class node_multiplayer_route,node_multiplayer_logic,node_matchmaking,node_multiplayer_state,node_maps_service toneMint
class node_maps_route,node_map_creation,node_competitions toneRose
class node_account,node_signup,node_shop,node_shop_logic,node_player,node_account_service,node_google_maps,node_playsocket toneIndigo
```

## Components

### Entry and navigation

- [Game menu](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/MainMenu.svelte): `src/lib/components/MainMenu.svelte`
- [Game route](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/%2Bpage.svelte): `src/routes/(game)/+page.svelte`
- [Game layout](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/%2Blayout.svelte): `src/routes/(game)/+layout.svelte`

### Guessing gameplay

- [Map page](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/MapPage.svelte): `src/lib/components/MapPage.svelte`
- [Map display](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/Map.svelte): `src/lib/components/Map.svelte`
- [Street View](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/Panorama.svelte): `src/lib/components/Panorama.svelte`
- **Location generation**
- [Round results](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/components/ResultScreen.svelte): `src/lib/components/ResultScreen.svelte`
- [Result calculations](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/resultScoreLogic.js): `src/lib/logic/resultScoreLogic.js`

### Multiplayer

- [Multiplayer pages](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/multiplayer/%2Bpage.svelte): `src/routes/(game)/(menu)/multiplayer/+page.svelte`
- [Multiplayer runtime](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/multiplayerLogic.js): `src/lib/logic/multiplayerLogic.js`
- [Matchmaking](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/logic/matchmakingLogic.js): `src/lib/logic/matchmakingLogic.js`
- [Match state](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/stores/context-specific/multiplayerStore.js): `src/lib/stores/context-specific/multiplayerStore.js`

### Maps and competitions

- [Map browsing](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/maps/%2Bpage.svelte): `src/routes/(game)/(menu)/maps/+page.svelte`
- [Map creation](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/maps/create/%2Bpage.svelte): `src/routes/(game)/(menu)/maps/create/+page.svelte`
- [Competitions](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/competitions/%2Bpage.svelte): `src/routes/(game)/(menu)/competitions/+page.svelte`

### Accounts and commerce

- [Account state](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/stores/accountStore.js): `src/lib/stores/accountStore.js`
- [Signup flow](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(other)/signup/%2Bpage.svelte): `src/routes/(other)/signup/+page.svelte`
- [Shop](https://github.com/therealpaulplay/openguessr/blob/main/src/routes/(game)/(menu)/shop/%2Bpage.svelte): `src/routes/(game)/(menu)/shop/+page.svelte`
- [Purchase operations](https://github.com/therealpaulplay/openguessr/blob/main/src/lib/utils/shopHelper.js): `src/lib/utils/shopHelper.js`

### Other components

- **Player**
- **Account backend**
- **Location server**
- **Google Maps**
- **PlaySocket**

## Connections

- Player → Game menu: opens
- Game menu → Game route: starts game
- Game route → Map page: renders
- Map page → Map display: displays map
- Map page → Street View: shows panorama
- Location server → Location generation: provides locations (evidence: `README.md`)
- Location generation → Map page: supplies locations (evidence: `README.md`)
- Google Maps → Street View: powers Street View (evidence: `README.md`)
- Map page → Round results: shows round result
- Round results → Result calculations: uses scoring
- Player → Multiplayer pages: opens multiplayer
- Multiplayer pages → Multiplayer runtime: runs matches
- Multiplayer runtime → Matchmaking: uses matchmaking
- Multiplayer runtime → Match state: updates state
- PlaySocket → Multiplayer runtime: supports multiplayer (evidence: `README.md`)
- Player → Map browsing: browses maps
- Player → Map creation: creates maps
- Player → Competitions: joins competitions
- Game menu → Account state: reads login state (evidence: `src/lib/components/MainMenu.svelte`)
- Game menu → Signup flow: prompts signup (evidence: `src/lib/components/MainMenu.svelte`)
- Player → Shop: browses shop
- Shop → Purchase operations: handles purchases
- Purchase operations → Account backend: requests purchases (evidence: `src/lib/utils/shopHelper.js`)
- Signup flow → Account backend: authenticates (evidence: `README.md`)
- Game route → Game layout: uses layout
