# benceszalaiii/valorantgeoguessr architecture

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

- Interactive diagram: https://gitdiagram.com/benceszalaiii/valorantgeoguessr
- Repository: https://github.com/benceszalaiii/valorantgeoguessr

## Overview

1. **Overall shape**
   This is a **static browser game**: HTML entry pages, shared JavaScript for behavior, and CSS for presentation. There is no obvious server-side application layer in the repo tree; the runtime appears to be the client browser plus static asset hosting.

2. **Localized page structure**
   The app is duplicated by language into `en/`, `hu/`, `de/`, `es/`, `fr/`, `jp/`, and `ar/`. Each language folder contains its own `index.html`, `game.html`, `leaderboard.html`, and `options.html`, which suggests the UI text/navigation is localized per page while the core behavior is shared.

3. **Core navigation entrypoint**
   The root `index.html` is the top-level entry, likely acting as the language selection or main landing page. From there, users move into the game, leaderboard, and options screens within the chosen language subtree.

4. **Shared application logic**
   The `javascript/` directory holds the main runtime modules:
   - `game.js` for gameplay flow
   - `leaderboard.js` for score/ranking views and submission
   - `options.js` for user settings
   - `index.js` for landing-page behavior
   - `locations.js` for map/location data
   - `database.js` for persistence/data access
   - `cookies.js` for browser-stored preferences or session state  
   This separation implies a modular client-side architecture with feature-specific scripts.

5. **Game flow**
   The central loop is likely: load a map/location set, present an image or scene, let the player guess, calculate distance/score, then advance through rounds and maps. The presence of `sources/<Map>/<Difficulty>/` strongly indicates the game selects content by **map and difficulty**.

6. **Content model**
   The `sources/` tree is the main content boundary:
   - map folders for **Ascent, Bind, Breeze, Fracture, Haven, Icebox, Lotus, Pearl, Split**
   - difficulty subfolders: **Easy, Medium, Hard**
   - additional asset groups: `Logo`, `minimaps`, and `lang`  
   This looks like a curated content pack of images and localization resources rather than dynamically generated data.

7. **Leaderboard and persistence**
   `leaderboard.html` in each language and `javascript/leaderboard.js` suggest a separate ranking screen. `database.js` plus `cookies.js` imply that scores/settings are persisted on the client side and/or through a small data-access abstraction. The repo tree does not reveal a traditional backend service, so leaderboard storage is likely browser-based or handled via a lightweight external data layer hidden behind `database.js`.

8. **Options/settings boundary**
   `options.html` and `javascript/options.js` represent a settings subsystem, likely controlling game preferences such as language, difficulty, sound, or display behavior. `cookies.js` indicates these preferences are stored across sessions in browser cookies or similar client storage.

9. **Styling separation**
   Styling is split by feature in `style/`:
   - `style.css` for shared/global layout
   - `game.css`, `leaderboard.css`, `options.css`, `submit.css` for feature-specific views  
   That suggests each screen is treated as a distinct UI state with its own layout constraints rather than one SPA shell.

10. **Authoring/tooling subsystem**
   The `tools/` directory (`index.js`, `map.html`, `style.css`) is a separate internal tool, likely for preparing or previewing map images/content before they are placed into `sources/`. This is an important boundary: the main game consumes curated assets, while `tools/` supports content creation/maintenance.

11. **Data flow summary**
   User input flows from localized HTML pages into shared JS, which reads map assets from `sources/`, tracks preferences via cookies, and writes/reads score data through the database abstraction. The main external dependency is the browser itself; the only other named integration in the README is the GeoGuessr-style gameplay concept, not an API dependency.

12. **What to show in an architecture diagram**
   A clean diagram would have three main layers:  
   - **Localized pages** (`<lang>/...html`, root `index.html`)  
   - **Shared client logic** (`javascript/*.js`)  
   - **Static content/assets** (`sources/`, `style/`)  
   with a side branch for **tools/** as a content-authoring utility and a small **persistence layer** behind `database.js`/`cookies.js`.

Main entry points: [`javascript/game.js`](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/game.js) (Game core), [`javascript/leaderboard.js`](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/leaderboard.js) (Leaderboard), [`sources`](https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources) (Maps), [`javascript/options.js`](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/options.js) (Options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pages["Localized pages"]
  node_root_index["Landing<br/>html entry<br/>[index.html]"]
  node_lang_pages["Lang pages<br/>localized html"]
end

subgraph group_logic["Shared logic"]
  node_index_js["Home logic<br/>ui script<br/>[index.js]"]
  node_game_js["Game core<br/>game runtime<br/>[game.js]"]
  node_leaderboard_js["Leaderboard<br/>ranking ui<br/>[leaderboard.js]"]
  node_options_js["Options<br/>settings ui<br/>[options.js]"]
  node_locations_js["Locations<br/>map data<br/>[locations.js]"]
  node_database_js["Database<br/>persistence layer<br/>[database.js]"]
  node_cookies_js["Cookies<br/>client storage<br/>[cookies.js]"]
end

subgraph group_content["Static content"]
  node_map_assets[("Maps<br/>content pack")]
  node_logos_assets["Logos<br/>asset pack"]
  node_mini_assets["Minimaps<br/>asset pack"]
  node_lang_assets["Lang assets<br/>localization"]
end

subgraph group_ui["Styles"]
  node_global_css["Global CSS<br/>shared styles<br/>[style.css]"]
  node_game_css["Game CSS<br/>feature styles<br/>[game.css]"]
  node_leader_css["Leaderboard CSS<br/>feature styles<br/>[leaderboard.css]"]
  node_options_css["Options CSS<br/>feature styles<br/>[options.css]"]
  node_submit_css["Submit CSS<br/>feature styles<br/>[submit.css]"]
end

subgraph group_tools["Tooling"]
  node_tool_index["Tool UI<br/>authoring tool<br/>[index.js]"]
  node_tool_map["Map editor<br/>tool page<br/>[map.html]"]
  node_tool_css["Tool CSS<br/>tool styles<br/>[style.css]"]
end

node_root_index -->|"loads"| node_index_js
node_root_index -->|"styles"| node_global_css
node_lang_pages -->|"game page"| node_game_js
node_lang_pages -->|"leaderboard"| node_leaderboard_js
node_lang_pages -->|"options"| node_options_js
node_lang_pages -->|"styles"| node_global_css
node_game_js -->|"uses"| node_locations_js
node_game_js -->|"stores"| node_database_js
node_game_js -->|"reads"| node_cookies_js
node_leaderboard_js -->|"reads/writes"| node_database_js
node_leaderboard_js -->|"reads"| node_cookies_js
node_options_js -->|"saves"| node_cookies_js
node_locations_js -->|"indexes"| node_map_assets
node_map_assets -.->|"includes"| node_logos_assets
node_map_assets -.->|"includes"| node_mini_assets
node_map_assets -.->|"includes"| node_lang_assets
node_game_js -->|"styles"| node_game_css
node_leaderboard_js -->|"styles"| node_leader_css
node_options_js -->|"styles"| node_options_css
node_leaderboard_js -->|"styles"| node_submit_css
node_tool_index -->|"opens"| node_tool_map
node_tool_index -->|"styles"| node_tool_css
node_tool_map -->|"edits/uses"| node_map_assets

click node_root_index "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/index.html"
click node_index_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/index.js"
click node_game_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/game.js"
click node_leaderboard_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/leaderboard.js"
click node_options_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/options.js"
click node_locations_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/locations.js"
click node_database_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/database.js"
click node_cookies_js "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/cookies.js"
click node_map_assets "https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources"
click node_logos_assets "https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources/Logo"
click node_mini_assets "https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources/minimaps"
click node_lang_assets "https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources/lang"
click node_global_css "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/style.css"
click node_game_css "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/game.css"
click node_leader_css "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/leaderboard.css"
click node_options_css "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/options.css"
click node_submit_css "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/submit.css"
click node_tool_index "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/tools/index.js"
click node_tool_map "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/tools/map.html"
click node_tool_css "https://github.com/benceszalaiii/valorantgeoguessr/blob/master/tools/style.css"

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_root_index,node_lang_pages toneBlue
class node_index_js,node_game_js,node_leaderboard_js,node_options_js,node_locations_js,node_database_js,node_cookies_js toneAmber
class node_map_assets,node_logos_assets,node_mini_assets,node_lang_assets toneMint
class node_global_css,node_game_css,node_leader_css,node_options_css,node_submit_css toneRose
class node_tool_index,node_tool_map,node_tool_css toneIndigo
```

## Components

### Localized pages

Root and language-specific HTML entry points

- [Landing](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/index.html): html entry · Top-level entry page · `index.html`
- **Lang pages**: localized html · Per-language game, leaderboard, and options screens

### Shared logic

Client-side JavaScript modules

- [Home logic](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/index.js): ui script · Landing-page behavior · `javascript/index.js`
- [Game core](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/game.js): game runtime · Gameplay flow and round handling · `javascript/game.js`
- [Leaderboard](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/leaderboard.js): ranking ui · Scoreboard display and submission flow · `javascript/leaderboard.js`
- [Options](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/options.js): settings ui · User preferences and settings behavior · `javascript/options.js`
- [Locations](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/locations.js): map data · Map and location metadata · `javascript/locations.js`
- [Database](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/database.js): persistence layer · Score and data access abstraction · `javascript/database.js`
- [Cookies](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/javascript/cookies.js): client storage · Browser-stored preferences and session state · `javascript/cookies.js`

### Static content

Game maps, imagery, and language assets

- [Maps](https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources): content pack · Per-map source folders with difficulty variants · `sources`
- [Logos](https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources/Logo): asset pack · Brand and UI imagery · `sources/Logo`
- [Minimaps](https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources/minimaps): asset pack · Mini-map imagery for gameplay UI · `sources/minimaps`
- [Lang assets](https://github.com/benceszalaiii/valorantgeoguessr/tree/master/sources/lang): localization · Shared language resources · `sources/lang`

### Styles

Global and feature-specific CSS

- [Global CSS](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/style.css): shared styles · Base layout and shared presentation · `style/style.css`
- [Game CSS](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/game.css): feature styles · Game screen styling · `style/game.css`
- [Leaderboard CSS](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/leaderboard.css): feature styles · Leaderboard screen styling · `style/leaderboard.css`
- [Options CSS](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/options.css): feature styles · Options screen styling · `style/options.css`
- [Submit CSS](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/style/submit.css): feature styles · Submission dialog styling · `style/submit.css`

### Tooling

Content-authoring utilities

- [Tool UI](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/tools/index.js): authoring tool · Map/content preparation entrypoint · `tools/index.js`
- [Map editor](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/tools/map.html): tool page · Map preview or editing page · `tools/map.html`
- [Tool CSS](https://github.com/benceszalaiii/valorantgeoguessr/blob/master/tools/style.css): tool styles · Styling for the authoring tool · `tools/style.css`

## Connections

- Landing → Home logic: loads · Landing page behavior
- Landing → Global CSS: styles · Shared layout and presentation
- Lang pages → Game core: game page · Localized gameplay screens use the shared runtime
- Lang pages → Leaderboard: leaderboard · Localized scoreboard screens use shared logic
- Lang pages → Options: options · Localized settings screens use shared logic
- Lang pages → Global CSS: styles · Shared base styling
- Game core → Locations: uses · Loads map/location metadata
- Game core → Database: stores · Persists score or run data
- Game core → Cookies: reads · Reads player preferences
- Leaderboard → Database: reads/writes · Leaderboard data access
- Leaderboard → Cookies: reads · Language or preference state
- Options → Cookies: saves · Persists settings across sessions
- Locations → Maps: indexes · Map content hierarchy
- Maps → Logos: includes · Shared imagery assets
- Maps → Minimaps: includes · Mini-map imagery assets
- Maps → Lang assets: includes · Localization resources
- Game core → Game CSS: styles · Game view styling
- Leaderboard → Leaderboard CSS: styles · Leaderboard view styling
- Options → Options CSS: styles · Options view styling
- Leaderboard → Submit CSS: styles · Submission UI styling
- Tool UI → Map editor: opens · Tool entry to map page
- Tool UI → Tool CSS: styles · Tool-specific styling
- Map editor → Maps: edits/uses · Authoring tool works on content packs
