# woutdp/geoquest architecture

> Architecture diagram of the GitHub repository woutdp/geoquest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/woutdp/geoquest
- Repository: https://github.com/woutdp/geoquest

## Overview

##### Project type and purpose
- This is a full-stack, SvelteKit-based Progressive Web App (“map quiz game”) that runs entirely on Cloudflare Pages/Workers.
- On the client side it delivers a rich, interactive geography quiz (maps, achievements, quests, multilingual UIs, sounds). On the server side it provides a small set of serverless endpoints (e.g., a “buy me a coffee” webhook).

##### File structure
- Top-level config files (svelte.config.js, vite.config.js, wrangler.toml) signal a SvelteKit/Vite app deployed as Cloudflare Workers/Pages.
- src/routes – SvelteKit pages & server routes (/api/webhooks/coffee).
- src/lib – core components and domain logic:
– Game logic & state (Game.svelte, store.ts, map.ts, jwt.ts)
– Static data assets (maps, quests, translations)
– Utility modules (utils.ts, sounds.ts)
- static – truly static files (ads.txt, manifest, robots.txt).
- service-worker.ts – PWA caching logic.
- schema.sql – (future or external) persistence schema (not currently used in code).

##### README
- Standard SvelteKit dev/build scripts.
- Translations guidelines.

a. Main components
- Browser (Client UI):
– SvelteKit SPA shell (SSR entry + hydration)
– Service Worker (offline caching, asset routing)
– Game logic components (Game.svelte + store)
– UI, map, assets loader modules
- CDN/Static Host (Cloudflare Pages):
- Serverless Runtime (Cloudflare Workers):
– SvelteKit SSR endpoints under /routes (SSR of pages, SSR+API handlers)
– API webhook endpoint (/api/webhooks/coffee) for third-party integration
- External Services:
– BuyMeACoffee (incoming webhooks)
– Possible analytics or other integrations
- (Optionally) Database or KV store:
– Represent schema.sql as a future or external DB component or Cloudflare D1/KV

b. Relationships & interactions
– On page load, Browser → CDN: fetch HTML/JS/CSS (via global CDN edge).
– Service Worker intercepts requests, serves cached assets or falls back to network.
– Browser ↔ Serverless Runtime for SSR or data calls.
– Browser loads static JSON (maps/quests/translations) directly from CDN or via fetch.
– API webhook: Cloudflare Worker → external “BuyMeACoffee” service.
– (If DB used) Worker endpoints → Database.

c. Architectural patterns & design principles
– Hybrid SSR + client hydration (SvelteKit)
– PWA with Service Worker for offline/fast caching
– Serverless functions for minimal backend (edge computing)
– Separation of concerns: UI components vs domain logic vs data assets vs translations
– Asset-heavy static hosting, “map/quest” micro-data files

d. Key technologies & frameworks
– SvelteKit & Vite for build and routing
– Tailwind CSS / PostCSS for styling
– Cloudflare Pages / Workers (wrangler.toml) for deployment
– Service Worker API for PWA caching
– JSON-based assets (maps, translations, quests)

##### Elements
– HTML/JS/CSS/JSON asset requests (Browser → CDN)
– SSR & API calls (Browser → Worker → [optional DB])
– Webhook call (Worker → BuyMeACoffee)
– Client-side (blue) vs Static (green) vs Dynamic/serverless (orange) vs External (purple)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        SPA["SvelteKit SPA shell"]:::client
        SW["Service Worker"]:::client
        GameComp["Game.svelte"]:::client
        Store["store.ts"]:::client
        MapLogic["map.ts"]:::client
        JWT["jwt.ts"]:::client
        UIComp["UI Components"]:::client
        MapVis["Map Visualization"]:::client
        Icons["Icon Components"]:::client
        Utils["utils.ts"]:::client
    end

    %% Static Asset Layer
    subgraph "Static Asset Layer (CDN)"
        Bundles["HTML/CSS/JS Bundles"]:::static
        Achievements["achievements.json"]:::static
        DailyQuest["daily-quest.json"]:::static
        MapsData["maps/"]:::static
        QuestsData["quests/"]:::static
        Sounds["assets/sounds/"]:::static
        Manifest["site.webmanifest"]:::static
        Robots["robots.txt"]:::static
        AdsTxt["ads.txt"]:::static
        BrowserConfig["browserconfig.xml"]:::static
    end

    %% Serverless Edge Layer
    subgraph "Serverless Edge Layer"
        SSR["SvelteKit SSR / routes"]:::server
        Webhook["Coffee Webhook Endpoint"]:::server
    end

    %% External Services
    subgraph "External Services"
        Buy["BuyMeACoffee"]:::external
        DB["Future DB (D1/KV)"]:::external
    end

    %% App Shell & Config
    subgraph "App Shell & Config"
        AppHTML["app.html"]:::static
        AppCSS["app.css"]:::static
        SvelteConfig["svelte.config.js"]:::static
        ViteConfig["vite.config.js"]:::static
        Wrangler["wrangler.toml"]:::static
    end

    %% Connections
    SPA -->|"fetch bundles"| Bundles
    SPA -->|"fetch JSON assets"| Achievements
    SPA -->|"fetch JSON assets"| DailyQuest
    SPA -->|"fetch JSON assets"| MapsData
    SPA -->|"fetch JSON assets"| QuestsData
    SPA -->|"fetch sounds"| Sounds
    SPA -->|"fetch manifest"| Manifest
    SPA -->|"fetch robots.txt"| Robots
    SPA -->|"fetch ads.txt"| AdsTxt
    SPA -->|"fetch browserconfig.xml"| BrowserConfig

    SW -->|"cache first for assets"| Bundles
    SW -->|"cache first for JSON"| Achievements
    SW -->|"cache first for sounds"| Sounds
    SW -->|"fallback to network for dynamic"| SSR

    SPA -->|"SSR & API calls"| SSR
    SSR -->|"webhook call"| Buy
    SSR -->|"optional DB reads"| DB

    %% Click Events
    click SSR "https://github.com/woutdp/geoquest/tree/master/src/routes/[[locale]]/"
    click Webhook "https://github.com/woutdp/geoquest/blob/master/src/routes/api/webhooks/coffee/+server.ts"
    click SW "https://github.com/woutdp/geoquest/blob/master/service-worker.ts"
    click Manifest "https://github.com/woutdp/geoquest/blob/master/static/site.webmanifest"
    click Robots "https://github.com/woutdp/geoquest/blob/master/static/robots.txt"
    click AdsTxt "https://github.com/woutdp/geoquest/blob/master/static/ads.txt"
    click BrowserConfig "https://github.com/woutdp/geoquest/blob/master/static/browserconfig.xml"
    click GameComp "https://github.com/woutdp/geoquest/blob/master/src/lib/Game.svelte"
    click Store "https://github.com/woutdp/geoquest/blob/master/src/lib/store.ts"
    click MapLogic "https://github.com/woutdp/geoquest/blob/master/src/lib/map.ts"
    click JWT "https://github.com/woutdp/geoquest/blob/master/src/lib/jwt.ts"
    click UIComp "https://github.com/woutdp/geoquest/tree/master/src/lib/ui/"
    click MapVis "https://github.com/woutdp/geoquest/tree/master/src/lib/map/"
    click Icons "https://github.com/woutdp/geoquest/tree/master/src/lib/icons/"
    click Achievements "https://github.com/woutdp/geoquest/blob/master/src/lib/assets/data/achievements.json"
    click DailyQuest "https://github.com/woutdp/geoquest/blob/master/src/lib/assets/data/daily-quest.json"
    click MapsData "https://github.com/woutdp/geoquest/tree/master/src/lib/assets/maps/"
    click QuestsData "https://github.com/woutdp/geoquest/tree/master/src/lib/assets/quests/"
    click Sounds "https://github.com/woutdp/geoquest/tree/master/src/lib/assets/sounds/"
    click Utils "https://github.com/woutdp/geoquest/blob/master/src/lib/utils.ts"
    click AppHTML "https://github.com/woutdp/geoquest/blob/master/src/app.html"
    click AppCSS "https://github.com/woutdp/geoquest/blob/master/src/app.css"
    click SvelteConfig "https://github.com/woutdp/geoquest/blob/master/svelte.config.js"
    click ViteConfig "https://github.com/woutdp/geoquest/blob/master/vite.config.js"
    click Wrangler "https://github.com/woutdp/geoquest/blob/master/wrangler.toml"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000
    classDef static fill:#90EE90,stroke:#000
    classDef server fill:#FFD580,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
```
