How zeuidon/globetrotter works
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