# zeuidon/globetrotter architecture

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

- Interactive diagram: https://gitdiagram.com/zeuidon/globetrotter
- Repository: https://github.com/zeuidon/globetrotter

## Overview

##### Project Type and Purpose
- Globetrotter is a full-stack web application for interactive geography-based gaming.
- Frontend: React.js SPA that presents clues, tracks score, and shows leaderboards.
- Backend: FastAPI service (Python) exposing REST endpoints for game logic, user profiles, and leaderboards.
- Storage: SQLite via SQLAlchemy for persistent data (users, scores, destinations).

##### File Structure
- Top Level:
- README.md – overview and instructions
- backend/ – FastAPI app and tests
- frontend/ – React project with public assets and source components
- backend/:
- app.py – FastAPI entry point
- add_destination.py – script to load new destinations
- destinations.json – seed data
- globetrotter.db – SQLite file
- tests/ – pytest suite for API validation
- frontend/:
- public/ – static HTML, manifest, robots.txt
- src/ – React components (Game, Leaderboard, UserProfile, etc.), app entry (index.js)
- package.json – dependencies and scripts

##### README for Additional Insights
- Tech Stack: React.js, FastAPI, SQLAlchemy, SQLite
- Features: gamification (score tracking), leaderboards, user profiles
- Startup scripts: uvicorn for backend, npm start for frontend
- Testing: pytest for backend, React Testing Library for frontend

a. Main Components
1. User’s Web Browser (Client)
2. React Frontend (SPA)
3. API Layer (FastAPI service)
4. Data Layer (SQLite via SQLAlchemy)
5. Static Asset Store (public folder, served by Node/Dev Server or CDN)

b. Relationships and Data Flows
- User → React SPA: interacts via HTTP/HTTPS
- React SPA → FastAPI: REST calls (e.g., /challenge, /submit, /leaderboard)
- FastAPI → SQLite: CRUD operations on users, scores, destinations
- add_destination.py → destinations.json → FastAPI loads into DB
- Tests (pytest) → FastAPI endpoints

c. Architectural Patterns & Design Principles
- Separation of Concerns: clear split between UI and API
- API-Driven Design: all operations on game state via REST endpoints
- Modular Components: React components for individual UI features
- Monolithic Service: single FastAPI process handling business logic and data access

d. Key Technologies
- React.js with Hooks for state and UI
- FastAPI + Uvicorn for asynchronous, high-performance API
- SQLAlchemy ORM mapping to SQLite file database
- Pytest and React Testing Library for unit/integration tests

- Clear, concise labels for each service, client, and data store.
- User Interface (frontend)
- API Service (backend)
- Persistence Layer (database / seed data)
- Static Assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    title["Globetrotter System Architecture"]

    subgraph "Client"
        U["User's Web Browser"]:::external
    end

    subgraph "Frontend (React.js SPA)"
        entry["index.js"]:::frontend
        appjs["App.js"]:::frontend
        appcss["App.css"]:::frontend
        components["Components"]:::frontend
        public["Public Assets"]:::static
        pkg["package.json"]:::static
        lock["package-lock.json"]:::static
        ftests["React Tests"]:::test
    end

    components --> game["Game.js"]:::frontend
    components --> lb["Leaderboard.js"]:::frontend
    components --> up["UserProfile.js"]:::frontend
    components --> st["ScoreTracker.js"]:::frontend
    components --> dc["DestinationCard.js"]:::frontend
    components --> cb["ChallengeButton.js"]:::frontend
    components --> af["AnswerFeedback.js"]:::frontend
    components --> gr["GameResult.js"]:::frontend

    public --> html["index.html"]:::static
    public --> manifest["manifest.json"]:::static
    public --> robots["robots.txt"]:::static

    subgraph "Backend (FastAPI Service)"
        api["app.py"]:::backend
        deps["requirements.txt"]:::backend
        loader["add_destination.py"]:::backend
        seed["destinations.json"]:::db
        db["globetrotter.db"]:::db
        btests["Pytest Suite"]:::test
    end

    U -->|"Loads SPA"| entry
    entry -->|"Renders"| appjs
    appjs -->|"Uses Styles"| appcss
    appjs -->|"Mounts"| components
    appjs -->|"Serves Assets"| public
    appjs -->|"API Calls"| api
    api -->|"CRUD via SQLAlchemy"| db
    api -->|"Reads Seed"| seed
    loader -->|"Seeds DB"| seed
    loader -->|"Writes to"| db
    btests -.->|"Tests Endpoints"| api
    ftests -.->|"Tests UI"| entry

    classDef external fill:#a2d2ff,stroke:#000;
    classDef frontend fill:#ffafcc,stroke:#000;
    classDef backend fill:#bde0fe,stroke:#000;
    classDef db fill:#cdb4db,stroke:#000,stroke-dasharray: 5 5;
    classDef static fill:#caffbf,stroke:#000;
    classDef test fill:#ffe066,stroke:#000,stroke-dasharray: 2 2;

    click entry "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/index.js"
    click appjs "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/App.js"
    click appcss "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/App.css"
    click game "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/Game.js"
    click lb "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/Leaderboard.js"
    click up "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/UserProfile.js"
    click st "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/ScoreTracker.js"
    click dc "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/DestinationCard.js"
    click cb "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/ChallengeButton.js"
    click af "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/AnswerFeedback.js"
    click gr "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/components/GameResult.js"
    click html "https://github.com/zeuidon/globetrotter/blob/main/frontend/public/index.html"
    click manifest "https://github.com/zeuidon/globetrotter/blob/main/frontend/public/manifest.json"
    click robots "https://github.com/zeuidon/globetrotter/blob/main/frontend/public/robots.txt"
    click pkg "https://github.com/zeuidon/globetrotter/blob/main/frontend/package.json"
    click lock "https://github.com/zeuidon/globetrotter/blob/main/frontend/package-lock.json"
    click ftests "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/App.test.js"
    click ftests "https://github.com/zeuidon/globetrotter/blob/main/frontend/src/setupTests.js"
    click api "https://github.com/zeuidon/globetrotter/blob/main/backend/app.py"
    click deps "https://github.com/zeuidon/globetrotter/blob/main/backend/requirements.txt"
    click loader "https://github.com/zeuidon/globetrotter/blob/main/backend/add_destination.py"
    click seed "https://github.com/zeuidon/globetrotter/blob/main/backend/destinations.json"
    click db "https://github.com/zeuidon/globetrotter/blob/main/backend/globetrotter.db"
    click btests "https://github.com/zeuidon/globetrotter/blob/main/backend/tests/test_main.py"
    click title "https://github.com/zeuidon/globetrotter/blob/main/README.md"
    click title "https://github.com/zeuidon/globetrotter/blob/main/frontend/README.md"
```
