# amaymani/globetrotter architecture

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

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

## Overview

##### Project Type and Purpose
- Globetrotter is an interactive quiz game built with Next.js and React. It tests players’ knowledge of global destinations using dynamic quizzes and engaging UI animations. The game includes features like high score tracking, authentication using NextAuth.js, and social sharing.
- Given the README and file structure, you are handling a full-stack application with a strong emphasis on both frontend interactivity and backend API endpoints powered by Node.js and MongoDB.

##### Analyzing the File Structure
- At the top level, you have configuration files (e.g., next.config.mjs, jsconfig.json, postcss.config.mjs, package.json) which indicate a Next.js based application.
- The "public" directory holds static assets.
- The "src" folder is organized with subdirectories:
- components: Contains both core components (Fact, Hero, Navbar, Quiz, ScoreCard) and special UI modules, including the "magicui" directory for animations (e.g., confetti.jsx) and the "ui" directory for reusable UI elements (badge, button, etc.).
- lib: Holds utility logic such as the MongoDB connection (mongo.js) and helper functions (utils.js).
- models: Contains data schema definitions (like the user model).
- pages: Contains Next.js pages including the entry points _app.js and _document.js, as well as API routes (e.g., authentication via [...nextauth].js, highscore, login, and random-dest).
- The presence of the "api" directory under pages reveals that this project leverages serverless functions or API routes to handle backend operations.

##### Key Components and Their Relationships
a. Frontend/UI:
- Pages: The home page (index.js) renders the interactive game UI integrated with various components.
- UI Components:
- Navbar, Hero, Fact, Quiz, ScoreCard for display and quiz logic.
- Additional UI elements (badge, button, dialog, etc.) and animations (magicui/confetti) to improve user experience.
b. Backend/API:
- API routes for handling user authentication (auth/[...nextauth].js, login.js) and game logic (highscore.js, random-dest.js, invite.js).
- These endpoints connect the frontend to the MongoDB database for persistent data storage.
c. Database:
- MongoDB managed via a dedicated library file (mongo.js) within "lib" and Mongoose models such as user.js in the "models" directory.
- High score tracking is implemented through API endpoints that interact with these models.
d. Utility/Configuration:
- Configuration files (next.config.mjs, jsconfig.json, postcss.config.mjs) ensure that build, performance, and styling are integrated seamlessly.
- The components.json file provides metadata for the UI components which could outline composition or design guidelines.

##### Architectural Patterns and Design Principles
- Separation of concerns is clear. The project separates frontend components, backend API endpoints, and database models.
- The use of Next.js facilitates server-side rendering and API route management, streamlining the integration between frontend and backend.
- Modular design is employed in the components (both the core ones and the reusable UI elements), allowing for easier maintenance and potential reuse.
- Tailwind CSS and PostCSS contribute to styling, while React Hooks manage state across the application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        subgraph "Page Routing"
            PageIndex("Index Page"):::frontend
            AppPage("_app Page"):::frontend
            DocumentPage("_document Page"):::frontend
        end
        subgraph "UI Components"
            Quiz("Quiz Component"):::frontend
            Navbar("Navbar Component"):::frontend
            Hero("Hero Component"):::frontend
            Fact("Fact Component"):::frontend
            ScoreCard("ScoreCard Component"):::frontend
        end
        UIAnimation("UI Animations"):::frontend
        ReusableUI("Reusable UI Elements"):::frontend
    end

    %% Backend API Layer
    subgraph "Backend API"
        AuthAPI("Auth API Route"):::backend
        Highscore("Highscore API"):::backend
        RandomDest("Random-Dest API"):::backend
        Invite("Invite API"):::backend
        Login("Login API"):::backend
    end

    %% Database Layer
    subgraph "Database"
        MongoConn("MongoDB Connection"):::database
        subgraph "Mongoose Models"
            UserModel("User Model"):::database
            DestinationModel("Destination Model"):::database
        end
    end

    %% Utility & Configuration Layer
    subgraph "Utility & Configuration"
        NextConfig("Next Config"):::utility
        JSConfig("JSConfig"):::utility
        PostCSS("PostCSS Config"):::utility
        ComponentsMeta("Components Metadata"):::utility
        PackageConfig("Package Config"):::utility
    end

    %% Frontend Page Routing to UI Components
    PageIndex -->|"renders"| Quiz
    PageIndex -->|"renders"| Navbar
    PageIndex -->|"renders"| Hero
    PageIndex -->|"renders"| Fact
    PageIndex -->|"renders"| ScoreCard

    %% UI Components utilizing UI Animations and Reusable Elements
    Quiz -->|"uses"| UIAnimation
    Quiz -->|"uses"| ReusableUI
    Navbar -->|"uses"| ReusableUI
    Hero -->|"uses"| ReusableUI
    Fact -->|"uses"| ReusableUI
    ScoreCard -->|"uses"| ReusableUI

    %% UI Components calling Backend APIs
    Quiz -->|"fetches"| Highscore
    Quiz -->|"fetches"| RandomDest
    Quiz -->|"calls"| Invite
    Navbar -->|"calls"| AuthAPI
    Navbar -->|"calls"| Login

    %% Backend APIs interacting with Database
    AuthAPI -->|"queries"| MongoConn
    Highscore -->|"reads/writes"| MongoConn
    RandomDest -->|"reads"| MongoConn
    Invite -->|"writes"| MongoConn
    Login -->|"handles"| MongoConn

    %% MongoDB Connection utilizing Mongoose Models
    MongoConn -->|"establishes"| UserModel
    MongoConn -->|"establishes"| DestinationModel

    %% Utility & Configuration supporting Frontend and Backend
    NextConfig -->|"setsUp"| PageIndex
    JSConfig -->|"setsUp"| AppPage
    PostCSS -->|"styles"| ReusableUI
    ComponentsMeta -->|"guides"| Quiz
    PackageConfig -->|"manages"| AuthAPI
    PackageConfig -->|"manages"| Highscore

    %% Click Event Mappings for Frontend
    click Quiz "https://github.com/amaymani/globetrotter/blob/main/src/components/Quiz.js"
    click Navbar "https://github.com/amaymani/globetrotter/blob/main/src/components/Navbar.js"
    click Hero "https://github.com/amaymani/globetrotter/blob/main/src/components/Hero.js"
    click Fact "https://github.com/amaymani/globetrotter/blob/main/src/components/Fact.js"
    click ScoreCard "https://github.com/amaymani/globetrotter/blob/main/src/components/ScoreCard.js"
    click UIAnimation "https://github.com/amaymani/globetrotter/blob/main/src/components/magicui/confetti.jsx"
    click ReusableUI "https://github.com/amaymani/globetrotter/tree/main/src/components/ui"
    click PageIndex "https://github.com/amaymani/globetrotter/blob/main/src/pages/index.js"
    click AppPage "https://github.com/amaymani/globetrotter/blob/main/src/pages/_app.js"
    click DocumentPage "https://github.com/amaymani/globetrotter/blob/main/src/pages/_document.js"

    %% Click Event Mappings for Backend API
    click AuthAPI "https://github.com/amaymani/globetrotter/blob/main/src/pages/api/auth/[...nextauth].js"
    click Highscore "https://github.com/amaymani/globetrotter/blob/main/src/pages/api/highscore.js"
    click RandomDest "https://github.com/amaymani/globetrotter/blob/main/src/pages/api/random-dest.js"
    click Invite "https://github.com/amaymani/globetrotter/blob/main/src/pages/api/invite.js"
    click Login "https://github.com/amaymani/globetrotter/blob/main/src/pages/api/login.js"

    %% Click Event Mappings for Database
    click MongoConn "https://github.com/amaymani/globetrotter/blob/main/src/lib/mongo.js"
    click UserModel "https://github.com/amaymani/globetrotter/blob/main/src/models/user.js"
    click DestinationModel "https://github.com/amaymani/globetrotter/blob/main/src/models/destination.js"

    %% Click Event Mappings for Utility & Configuration
    click NextConfig "https://github.com/amaymani/globetrotter/blob/main/next.config.mjs"
    click JSConfig "https://github.com/amaymani/globetrotter/blob/main/jsconfig.json"
    click PostCSS "https://github.com/amaymani/globetrotter/blob/main/postcss.config.mjs"
    click ComponentsMeta "https://github.com/amaymani/globetrotter/blob/main/components.json"
    click PackageConfig "https://github.com/amaymani/globetrotter/blob/main/package.json"

    %% Styles
    classDef frontend fill:#b3cde0,stroke:#6497b1,stroke-width:2px;
    classDef backend fill:#ccebc5,stroke:#2b8c4d,stroke-width:2px;
    classDef database fill:#fdae61,stroke:#f46d43,stroke-width:2px;
    classDef utility fill:#decbe4,stroke:#9e9ac8,stroke-width:2px;
```
