# mohammedhamza0631/geogenius architecture

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

- Interactive diagram: https://gitdiagram.com/mohammedhamza0631/geogenius
- Repository: https://github.com/mohammedhamza0631/geogenius

## Overview

##### Project Type and Purpose
- GeoGenius is a full-stack interactive web application built using Next.js. Its main purpose is to provide a quiz that tests users’ knowledge of world capitals.
- The project uses React for the frontend, Tailwind CSS for styling, and Next.js API routes for handling backend logic.
- A PostgreSQL database managed through Prisma (with migrations) stores quiz data, user details, and scores.

##### File Structure
- Top-Level Organization:
- The "app" directory holds the main Next.js application files including pages (e.g., app/page.jsx, app/quiz/page.jsx, app/leaderboard/page.jsx), layout, styling (globals.css), and API routes (located in app/api/*).
- The "components" folder holds reusable React UI components like header, footer, quiz components (quiz-question, quiz-results, quiz-setup-form), and several UI components (in components/ui).
- The "lib" directory contains utility files that support tasks such as quiz data management (quiz-data.js), prisma connections (prisma.js), and utility functions for pin operations and cleanup.
- The "prisma" directory contains the schema and migration files for managing the PostgreSQL database.
- Configuration Files:
- Files like next.config.mjs, postcss.config.mjs, tailwind.config.js, and .eslintrc.json indicate project-specific configurations.
- The scripts folder holds additional helper scripts for tasks like cleaning up duplicates or updating high scores.

##### Key Components
a. Client/Frontend Layer:
- Pages and Views: Represent distinct routes such as Landing, Quiz, Start, and Leaderboard. These are defined in the "app" directory.
- UI Components: Include smaller building blocks from the "components" folder (header, footer, globe, quiz questions, results, etc.) that are rendered on the pages.
- State Management: The usage of React Context API from files like lib/quiz-context.js provides global state handling across the application.
b. Backend/API Layer:
- Next.js API Routes: Under the "app/api" directory you find various endpoints such as check-pin, check-username, set-pin, and user-scores. These endpoints handle server-side logic and data validation.
- Utility and Business Logic: The "lib" directory contains essential logic for data handling (e.g., lib/utils.js, lib/pin-utils.js) that is used by API routes.
c. Database Layer:
- PostgreSQL Database: Managed via Prisma ORM, with schema definitions in prisma/schema.prisma and migrations available in the migrations folder.
- Database Tools: Utilize the prisma.js file to connect, execute queries, and manage transactions.

##### Relationships and Interactions
- The Frontend (client side) sends HTTP requests to API endpoints for operations such as validating user inputs (e.g., checking username and pin), recording scores, and fetching leaderboard data.
- API endpoints process requests by using business logic from the utility libraries and interact with the PostgreSQL database via Prisma.
- The user data, quiz questions, and scores stored in the database feed back into the frontend for real-time updates (e.g., dynamic leaderboard).

##### Highlighting Architectural Patterns and Design Principles
- Separation of Concerns: The clear separation between frontend pages, reusable components, API routes, and business logic modularizes the application.
- Single Page Application (SPA) with Next.js: Uses client-side routing along with server-side API endpoints.
- Modular UI Design: Reusable UI components (including UI primitives from components/ui) promote a consistent and maintainable interface.
- Data Flow: Directional data flow from the user interaction layer (frontend) to the server (API routes) and then to the database ensures clarity in request handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        subgraph "Pages and Views"
            Home["Home Page"]
            Quiz["Quiz Page"]
            Leader["Leaderboard Page"]
            Start["Start Page"]
            Layout["Layout"]
        end
        subgraph "UI Components"
            Header["Header"]
            Footer["Footer"]
            Globe["Globe"]
            QQuestion["Quiz Question"]
            QResults["Quiz Results"]
            QSetup["Quiz Setup Form"]
            UIPrimitives["UI Primitives"]
        end
        QuizContext["Quiz Context"]
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        CheckPinAPI["Check Pin API"]
        CheckUsernameAPI["Check Username API"]
        SetPinAPI["Set Pin API"]
        UserScoresAPI["User Scores API"]
    end

    %% Utility & Scripts Layer
    subgraph "Business Logic"
        QuizData["Quiz Data"]
        Utils["Utils"]
        PinUtils["Pin Utils"]
        CleanupUtils["Cleanup Utils"]
        PrismaConnection["Prisma Connection"]
    end
    subgraph "Auxiliary Scripts"
        CleanupDup["Cleanup Duplicates Script"]
        UpdateBestScores["Update Best Scores Script"]
    end

    %% Database Layer
    subgraph "Database Layer"
        PrismaSchema["Prisma Schema"]
        PrismaMigrations["Prisma Migrations"]
    end

    %% Configuration Layer
    subgraph "Configuration"
        GlobalsCSS["Globals CSS"]
        NextConfig["Next Config"]
        PostCSSConfig["PostCSS Config"]
        TailwindConfig["Tailwind Config"]
        ESLintConfig["ESLint Config"]
    end

    %% Connections between Frontend and API
    Home -->|"validate_username"| CheckUsernameAPI
    Quiz -->|"submits_quiz_answers"| SetPinAPI
    Leader -->|"fetches_leaderboard"| UserScoresAPI

    %% UI Components interaction with state management
    QSetup -->|"updates_state"| QuizContext

    %% API endpoints use utility functions
    CheckPinAPI -->|"uses"| Utils
    CheckUsernameAPI -->|"uses"| Utils
    SetPinAPI -->|"uses"| Utils
    UserScoresAPI -->|"uses"| Utils

    %% API endpoints query the database via Prisma Connection
    CheckPinAPI -->|"queries"| PrismaConnection
    CheckUsernameAPI -->|"queries"| PrismaConnection
    SetPinAPI -->|"queries"| PrismaConnection
    UserScoresAPI -->|"queries"| PrismaConnection

    %% Prisma Connection interacts with Database
    PrismaConnection -->|"connects"| PrismaSchema
    PrismaConnection -->|"migrates"| PrismaMigrations

    %% Auxiliary Scripts operations
    CleanupDup -->|"cleans_duplicates"| QuizData
    UpdateBestScores -->|"updates_scores"| QuizData

    %% Layout uses configuration for styling
    Layout -->|"styled_by"| GlobalsCSS
    Layout -->|"configured_by"| NextConfig

    %% Class definitions for color coding
    class Home,Quiz,Leader,Start,Layout,Header,Footer,Globe,QQuestion,QResults,QSetup,UIPrimitives,QuizContext frontend
    class CheckPinAPI,CheckUsernameAPI,SetPinAPI,UserScoresAPI api
    class PrismaSchema,PrismaMigrations db
    class QuizData,Utils,PinUtils,CleanupUtils,PrismaConnection,CleanupDup,UpdateBestScores utility
    class GlobalsCSS,NextConfig,PostCSSConfig,TailwindConfig,ESLintConfig config

    %% Styles
    classDef frontend fill:#CDE7FF,stroke:#036,stroke-width:2px;
    classDef api fill:#FFE5B4,stroke:#C65,stroke-width:2px;
    classDef db fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef utility fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef config fill:#F2F3F4,stroke:#7F8C8D,stroke-width:2px;

    %% Click Events for Frontend Pages and Views
    click Home "https://github.com/mohammedhamza0631/geogenius/blob/main/app/page.jsx"
    click Quiz "https://github.com/mohammedhamza0631/geogenius/blob/main/app/quiz/page.jsx"
    click Leader "https://github.com/mohammedhamza0631/geogenius/blob/main/app/leaderboard/page.jsx"
    click Start "https://github.com/mohammedhamza0631/geogenius/blob/main/app/start/page.jsx"
    click Layout "https://github.com/mohammedhamza0631/geogenius/blob/main/app/layout.jsx"

    %% Click Events for UI Components
    click Header "https://github.com/mohammedhamza0631/geogenius/blob/main/components/header.jsx"
    click Footer "https://github.com/mohammedhamza0631/geogenius/blob/main/components/footer.jsx"
    click Globe "https://github.com/mohammedhamza0631/geogenius/blob/main/components/globe.jsx"
    click QQuestion "https://github.com/mohammedhamza0631/geogenius/blob/main/components/quiz-question.jsx"
    click QResults "https://github.com/mohammedhamza0631/geogenius/blob/main/components/quiz-results.jsx"
    click QSetup "https://github.com/mohammedhamza0631/geogenius/blob/main/components/quiz-setup-form.jsx"
    click UIPrimitives "https://github.com/mohammedhamza0631/geogenius/tree/main/components/ui"

    %% Click Event for State Management
    click QuizContext "https://github.com/mohammedhamza0631/geogenius/blob/main/lib/quiz-context.js"

    %% Click Events for API Routes
    click CheckPinAPI "https://github.com/mohammedhamza0631/geogenius/blob/main/app/api/check-pin/route.js"
    click CheckUsernameAPI "https://github.com/mohammedhamza0631/geogenius/blob/main/app/api/check-username/route.js"
    click SetPinAPI "https://github.com/mohammedhamza0631/geogenius/blob/main/app/api/set-pin/route.js"
    click UserScoresAPI "https://github.com/mohammedhamza0631/geogenius/blob/main/app/api/user-scores/route.js"

    %% Click Events for Utility/Business Logic
    click QuizData "https://github.com/mohammedhamza0631/geogenius/blob/main/lib/quiz-data.js"
    click Utils "https://github.com/mohammedhamza0631/geogenius/blob/main/lib/utils.js"
    click PinUtils "https://github.com/mohammedhamza0631/geogenius/blob/main/lib/pin-utils.js"
    click CleanupUtils "https://github.com/mohammedhamza0631/geogenius/blob/main/lib/cleanup-utils.js"
    click PrismaConnection "https://github.com/mohammedhamza0631/geogenius/blob/main/lib/prisma.js"

    %% Click Events for Database Layer
    click PrismaSchema "https://github.com/mohammedhamza0631/geogenius/blob/main/prisma/schema.prisma"
    click PrismaMigrations "https://github.com/mohammedhamza0631/geogenius/tree/main/prisma/migrations/20250310105719_init"

    %% Click Events for Configuration Files
    click GlobalsCSS "https://github.com/mohammedhamza0631/geogenius/blob/main/app/globals.css"
    click NextConfig "https://github.com/mohammedhamza0631/geogenius/blob/main/next.config.mjs"
    click PostCSSConfig "https://github.com/mohammedhamza0631/geogenius/blob/main/postcss.config.mjs"
    click TailwindConfig "https://github.com/mohammedhamza0631/geogenius/blob/main/tailwind.config.js"
    click ESLintConfig "https://github.com/mohammedhamza0631/geogenius/blob/main/.eslintrc.json"

    %% Click Events for Auxiliary Scripts
    click CleanupDup "https://github.com/mohammedhamza0631/geogenius/blob/main/scripts/cleanup-duplicates.js"
    click UpdateBestScores "https://github.com/mohammedhamza0631/geogenius/blob/main/scripts/update-best-scores.js"
```
