# vtchoo/whereami architecture

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

- Interactive diagram: https://gitdiagram.com/vtchoo/whereami
- Repository: https://github.com/vtchoo/whereami

## Overview

##### Project Type and Purpose
- The project is a front-end, single-page application that mimics GeoGuessr.
- It leverages Google Maps and Street View APIs and provides features such as random world locations and multiplayer challenges.
- The README further hints at planned features like region picking, bookmarking, player profiles, and ranking—so the architecture should be flexible to include new modules.

##### File Structure
- Top-level files indicate a standard Create React App structure with configuration (tsconfig.json, package.json, etc.) and a clear separation between public assets and source code.
- The src folder contains:
- Core application files (App.tsx, index.js, etc.)
- Contexts: Global state management for Alerts, Auth, and GoogleMaps.
- Pages: Different game screens (Home, Challenge, ChallengeResults, Login, SignUp, MyPlaces)
- Navigation: Routing logic organized into a general index.tsx and an internal navigation module.
- Services: API services for backend interactions, likely including communication with external APIs.
- Models: Data definitions for game entities such as Challenge, Location, User, etc.
- Hooks and Utils: Custom hooks (e.g., useDebounce) and utility functions supporting application logic.

a. Main Components:
- User Interface Layer: Represented by the React “Pages” and “Components” folders.
- Pages: Home, Challenge, ChallengeResults, Login, SignUp, MyPlaces.
- Components: Shared UI elements like Button, Header, Sidebar, Modal, etc.
- State Management Layer: The “Contexts” which include AlertsContext, AuthContext, GoogleMaps Context.
- Service Layer: “Services/api” acting as the intermediary for network calls to external APIs (e.g., Google Maps/Street View) and any backend interactions.
- Routing & Navigation: “Navigation” directory managing internal routes to different pages.
- Data Model Layer: “Models” folder defining schema and types for Challenges, Locations, Users, etc.
- Utility & Helper Functions: “Hooks” (e.g., useDebounce) and “Utils” (e.g., MathUtils, RouterUtils).

b. Relationships and Interactions:
- The UI elements on Pages use Components which in turn communicate with Contexts to access global application state (auth status, alerts, map data).
- Contexts (especially the GoogleMaps context) interact with external APIs via the Services layer.
- Navigation controls which page/component is rendered based on user interaction and context.
- Data flows from Services APIs into Models which are then used across contexts and components.
- Events from the UI can trigger updates in Contexts that propagate new state to all relevant Components.

c. Architectural Patterns and Design Principles:
- Component-Based Architecture: Clear separation of reusable UI components.
- Context API for Global State: Used to manage alerts, authentication, and external API integration (Google Maps).
- Separation of Concerns: Distinct folders for presentation (components/pages), application logic (contexts/services), and data models.
- Modular Design: Easy extension points for new features (e.g., planned profile page, region selection).

d. Relevant Technologies and Libraries:
- React with TypeScript for the UI.
- Context API for state management.
- Custom hooks (like useDebounce) for handling reactive logic.
- Integration with Google Maps and Street View APIs.
- CSS Modules for scoped styling across components.
- Possibly a testing framework (as seen in App.test.js and setupTests.js).

##### Details
- That every folder with significant functionality is represented.
- Do not be overly abstract—capture as many individual elements (components, contexts, navigation paths) as makes the architectural flow clear.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Navigation Layer
    subgraph "Navigation Layer"
        Nav["Navigation"]:::routing
    end

    %% UI Layer
    subgraph "UI Layer"
        subgraph "Pages"
            HomePage["Home"]:::uiPages
            ChallengePage["Challenge"]:::uiPages
            ChallengeResultsPage["ChallengeResults"]:::uiPages
            LoginPage["Login"]:::uiPages
            SignUpPage["SignUp"]:::uiPages
            MyPlacesPage["MyPlaces"]:::uiPages
        end
        subgraph "Components"
            Button["Button"]:::uiComponents
            Header["Header"]:::uiComponents
            Sidebar["Sidebar"]:::uiComponents
            MainLogo["MainLogo"]:::uiComponents
            Icon["Icon"]:::uiComponents
            Modal["Modal"]:::uiComponents
        end
    end

    %% State Management Layer
    subgraph "State Management Layer"
        AlertsCtx["Alerts Context"]:::state
        AuthCtx["Auth Context"]:::state
        GoogleMapsCtx["GoogleMaps Context"]:::state
    end

    %% Service & Data Layers
    subgraph "Service & Data Layers"
        ApiSvc["API Service"]:::service
        DataModel["Data Model Layer"]:::data
    end

    %% Utility & Helper Functions
    subgraph "Utility & Helper Functions"
        HooksNode["Hooks"]:::utility
        UtilsNode["Utils"]:::utility
    end

    %% Relationships and Data Flow
    Nav -->|"routes"| HomePage
    Nav -->|"routes"| ChallengePage
    Nav -->|"routes"| ChallengeResultsPage
    Nav -->|"routes"| LoginPage
    Nav -->|"routes"| SignUpPage
    Nav -->|"routes"| MyPlacesPage

    HomePage -->|"renders"| Button

    Button -->|"triggers"| AlertsCtx
    Button -->|"triggers"| AuthCtx
    Button -->|"triggers"| GoogleMapsCtx

    GoogleMapsCtx -->|"calls"| ApiSvc
    ApiSvc -->|"fetches"| DataModel

    HomePage -->|"uses"| HooksNode
    Button -->|"uses"| UtilsNode

    %% Styles for color coding
    classDef uiPages fill:#ccf,stroke:#333,stroke-width:2px;
    classDef uiComponents fill:#cfc,stroke:#333,stroke-width:2px;
    classDef state fill:#fcf,stroke:#333,stroke-width:2px;
    classDef routing fill:#fcc,stroke:#333,stroke-width:2px;
    classDef service fill:#cff,stroke:#333,stroke-width:2px;
    classDef data fill:#ffc,stroke:#333,stroke-width:2px;
    classDef utility fill:#f9c,stroke:#333,stroke-width:2px;

    %% Click Events
    click Button "https://github.com/vtchoo/whereami/tree/master/src/components/Button"
    click Header "https://github.com/vtchoo/whereami/tree/master/src/components/Header"
    click Sidebar "https://github.com/vtchoo/whereami/tree/master/src/components/Sidebar"
    click MainLogo "https://github.com/vtchoo/whereami/tree/master/src/components/MainLogo"
    click Icon "https://github.com/vtchoo/whereami/tree/master/src/components/Icon"
    click Modal "https://github.com/vtchoo/whereami/tree/master/src/components/Modal"
    click HomePage "https://github.com/vtchoo/whereami/tree/master/src/pages/Home"
    click ChallengePage "https://github.com/vtchoo/whereami/tree/master/src/pages/Challenge"
    click ChallengeResultsPage "https://github.com/vtchoo/whereami/tree/master/src/pages/ChallengeResults"
    click LoginPage "https://github.com/vtchoo/whereami/tree/master/src/pages/Login"
    click SignUpPage "https://github.com/vtchoo/whereami/tree/master/src/pages/SignUp"
    click MyPlacesPage "https://github.com/vtchoo/whereami/tree/master/src/pages/MyPlaces"
    click AlertsCtx "https://github.com/vtchoo/whereami/tree/master/src/contexts/AlertsContext"
    click AuthCtx "https://github.com/vtchoo/whereami/tree/master/src/contexts/AuthContext"
    click GoogleMapsCtx "https://github.com/vtchoo/whereami/tree/master/src/contexts/GoogleMaps"
    click Nav "https://github.com/vtchoo/whereami/tree/master/src/navigation"
    click ApiSvc "https://github.com/vtchoo/whereami/tree/master/src/services/api"
    click DataModel "https://github.com/vtchoo/whereami/tree/master/src/models"
    click HooksNode "https://github.com/vtchoo/whereami/tree/master/src/hooks"
    click UtilsNode "https://github.com/vtchoo/whereami/tree/master/src/utils"
```
