# spider-hand/geoguessmaster architecture

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

- Interactive diagram: https://gitdiagram.com/spider-hand/geoguessmaster
- Repository: https://github.com/spider-hand/geoguessmaster

## Overview

##### Project type and purpose
- From the README and file tree, this is “GeoguessMaster”: an open-source, PWA, real-time multiplayer geoguess game.
- Tech stack: Vue.js + TypeScript front end (src/), Firebase Hosting (firebase.json + public/ + index.html), Firebase Realtime Database, Firebase Cloud Functions (functions/), Google Maps & Street View APIs.

##### File structure
- Top level:
- Configuration: .eslintrc, .firebaserc, firebase.json, vite.config.ts, tsconfig.json, etc.
- Public assets & hosting: public/, index.html, manifest.json, service worker (registerServiceWorker.ts).
- Front end: src/ (App.vue, views/, components/, composables/, router/, stores/, utils/, assets/).
- Tests: src/__tests__/unit/… (Vitest).
- Backend/serverless: functions/src/index.ts (Cloud Functions), functions/package.json, tsconfig.json for functions.

##### README for additional insights
- Confirms multiplayer real-time via Firebase Realtime Database.
- PWA support, offline via service worker.
- Front end calls Google Maps & Street View APIs for map rendering.
- Cloud Functions likely orchestrate room creation, game lifecycle triggers on DB events.

##### Main components & their relations
a. Frontend (Vue PWA)
- Hosts UI, game views, state management (stores/ inGame, gameSettings, device).
- Communicates bidirectionally with Firebase Realtime Database over WebSockets / REST.
- Invokes Cloud Functions (HTTP or callable) for server-side logic (e.g., createGameRoom).
- Fetches map imagery from Google Maps JS API & Street View API.
- Service Worker caches static assets & enables offline behavior.
b. Firebase Hosting
- Serves static assets (index.html, JS bundles, images, manifest).
c. Firebase Realtime Database
- Central shared state: rooms, players, guesses, scores.
- Real-time sync across all clients.
d. Firebase Cloud Functions
- Triggered on HTTP calls or DB triggers for game lifecycle events, quota checks, cleanup.
e. External APIs
- Google Maps / Street View for map tiles & street imagery.

##### Architectural patterns & design principles
- Client-centric MVC (Vue components + Vuex-style stores).
- Serverless micro-backend (Cloud Functions for discrete units of logic).
- Real-time event-driven architecture via Realtime Database triggers.
- PWA pattern: service worker + manifest for offline/mobile support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Node
    Client["Client Browser (PWA)"]:::frontend

    %% Frontend Subgraph
    subgraph "Frontend (Vue PWA)" 
        direction TB
        subgraph "Source Code (src/)" 
            direction TB
            Src["Vue PWA Client (src/)"]:::code
            App["Root App Component (src/App.vue)"]:::code
            HomeView["Home Screen View (src/views/HomeView.vue)"]:::code
            GameView["Game Screen View (src/views/GameView.vue)"]:::code
            GameComps["Game UI Components (src/components/game/)"]:::code
            HomeComps["Home UI Components (src/components/home/)"]:::code
            SharedIcon["IconButtonComponent.vue"]:::code
            InGameStore["In-Game Store (src/stores/inGame.ts)"]:::code
            SettingsStore["Game Settings Store (src/stores/gameSettings.ts)"]:::code
            DeviceStore["Device Store (src/stores/device.ts)"]:::code
            Router["Router Config (src/router/index.ts)"]:::code
            UseCountdown["useCountdown.ts"]:::code
            UseMap["useMap.ts"]:::code
            UseStreetView["useStreetView.ts"]:::code
            FirebaseInit["Firebase Init (src/firebase/index.ts)"]:::code
            SWRegister["Service Worker Reg (src/registerServiceWorker.ts)"]:::code
        end
        subgraph "Public Assets & PWA" 
            direction TB
            Public["Public Assets (public/)"]:::assets
            Manifest["manifest.json"]:::assets
            Redirects["_redirects"]:::assets
            Robots["robots.txt"]:::assets
        end
        subgraph "Config & Tests" 
            direction TB
            FirebaseJSON["firebase.json"]:::config
            ViteConfig["vite.config.ts"]:::config
            TSConfig["tsconfig.json"]:::config
            TSNodeConfig["tsconfig.node.json"]:::config
            VitestConfig["vitest.config.ts"]:::config
            UnitTests["Unit Tests (src/__tests__/unit/)"]:::config
        end
    end

    %% Firebase Cloud Subgraph
    subgraph "Firebase Cloud" 
        direction TB
        Hosting["Firebase Hosting"]:::serverless
        RealtimeDB["Realtime Database"]:::database
        Functions["Cloud Functions"]:::serverless
    end

    %% External APIs
    subgraph "External Services" 
        direction TB
        GoogleMaps["Google Maps & Street View APIs"]:::external
    end

    %% Data Flows
    Hosting -->|serves static assets over HTTPS| Client
    Client -->|ws:// or HTTPS reads/writes| RealtimeDB
    Client -->|HTTP Callable| Functions
    RealtimeDB -->|onWrite triggers| Functions
    Functions -->|reads/writes| RealtimeDB
    Client -->|HTTPS requests| GoogleMaps

    %% Click Events
    click Src "https://github.com/spider-hand/geoguessmaster/tree/master/src/"
    click App "https://github.com/spider-hand/geoguessmaster/blob/master/src/App.vue"
    click HomeView "https://github.com/spider-hand/geoguessmaster/blob/master/src/views/HomeView.vue"
    click GameView "https://github.com/spider-hand/geoguessmaster/blob/master/src/views/GameView.vue"
    click GameComps "https://github.com/spider-hand/geoguessmaster/tree/master/src/components/game/"
    click HomeComps "https://github.com/spider-hand/geoguessmaster/tree/master/src/components/home/"
    click SharedIcon "https://github.com/spider-hand/geoguessmaster/blob/master/src/components/shared/IconButtonComponent.vue"
    click InGameStore "https://github.com/spider-hand/geoguessmaster/blob/master/src/stores/inGame.ts"
    click SettingsStore "https://github.com/spider-hand/geoguessmaster/blob/master/src/stores/gameSettings.ts"
    click DeviceStore "https://github.com/spider-hand/geoguessmaster/blob/master/src/stores/device.ts"
    click Router "https://github.com/spider-hand/geoguessmaster/blob/master/src/router/index.ts"
    click UseCountdown "https://github.com/spider-hand/geoguessmaster/blob/master/src/composables/game/useCountdown.ts"
    click UseMap "https://github.com/spider-hand/geoguessmaster/blob/master/src/composables/game/useMap.ts"
    click UseStreetView "https://github.com/spider-hand/geoguessmaster/blob/master/src/composables/game/useStreetView.ts"
    click FirebaseInit "https://github.com/spider-hand/geoguessmaster/blob/master/src/firebase/index.ts"
    click SWRegister "https://github.com/spider-hand/geoguessmaster/blob/master/src/registerServiceWorker.ts"
    click Public "https://github.com/spider-hand/geoguessmaster/tree/master/public/"
    click Manifest "https://github.com/spider-hand/geoguessmaster/blob/master/public/manifest.json"
    click Redirects "https://github.com/spider-hand/geoguessmaster/tree/master/public/_redirects"
    click Robots "https://github.com/spider-hand/geoguessmaster/blob/master/public/robots.txt"
    click FirebaseJSON "https://github.com/spider-hand/geoguessmaster/blob/master/firebase.json"
    click ViteConfig "https://github.com/spider-hand/geoguessmaster/blob/master/vite.config.ts"
    click TSConfig "https://github.com/spider-hand/geoguessmaster/blob/master/tsconfig.json"
    click TSNodeConfig "https://github.com/spider-hand/geoguessmaster/blob/master/tsconfig.node.json"
    click VitestConfig "https://github.com/spider-hand/geoguessmaster/blob/master/vitest.config.ts"
    click UnitTests "https://github.com/spider-hand/geoguessmaster/tree/master/src/__tests__/unit/"
    click Functions "https://github.com/spider-hand/geoguessmaster/blob/master/functions/src/index.ts"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef code fill:#EBF5FB,stroke:#1B4F72,color:#1A5276;
    classDef assets fill:#FDEDEC,stroke:#922B21,color:#641E16;
    classDef config fill:#FEF9E7,stroke:#7D6608,color:#7E5109;
    classDef serverless fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef database fill:#FCF3CF,stroke:#7D6608,color:#7E5109;
    classDef external fill:#FADBD8,stroke:#922B21,color:#78281F
```
