How vtchoo/whereami works
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.