# rya23/rubix25_27_nuclitron architecture

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

- Interactive diagram: https://gitdiagram.com/rya23/rubix25_27_nuclitron
- Repository: https://github.com/rya23/rubix25_27_nuclitron

## Overview

##### Main Components
- Client/Browser: Represents the end-user’s interaction point.
- Frontend Application (Next.js):
- Serverless API Routes: Inside “frontend/app/api,” endpoints such as check-avatar-status, delete-image, generate-avatar, and upload-image expose backend functionality within the same Next.js app.
- Components: The “frontend/components” folder holds UI widgets and interactive components (ChatBot, NavBar, MapComponent, Quiz components, etc.) that are used on these pages.
- Static Data & Assets: The “frontend/assets” and “frontend/data” directories provide images, JSON datasets, and historical information for rendering timelines, maps, and quizzes.
- Libraries & Utilities:
- “frontend/lib” contains helper modules (Firebase integration, custom utility functions) that underpin certain dynamic features like profile generation or image handling.
- Configuration & Build Tools:
- Files like “next.config.mjs”, “tailwind.config.ts”, and “tsconfig.json” configure and build the project’s UI and styling.

##### Relationships and Interactions
- Users accessing the application via browsers load the Next.js frontend.
- The dynamic pages (e.g., /chat, /quiz, /timeline) render by combining UI components with data fetched either from static JSON files or via internal API calls.
- API routes embedded in the app (in the “api” folder) handle user actions like checking avatar status, image generation, or image upload. Data flows from the browser to these endpoints (and vice versa using HTTP route handlers).
- Firebase and other libraries (from “lib”) are used by various parts of the application to manage data persistence, authentication, or real-time interactions.
- External multimedia or AI services could be referenced as additional dependencies though not explicitly visible in the file tree—highlight their potential roles in the overall flow.

##### Architectural Patterns and Key Design Principles
- Use of Next.js file-based routing for a clear separation of pages and API endpoints.
- Modular component-based UI design that allows reusability and separation of concerns (e.g., dedicated components for navigation, maps, chat interfaces, and gamification elements).
- Integration of serverless functions within the same project structure to handle backend logic without a separate backend service.
- Clear separation of static assets and dynamic data interaction, enabling optimal performance and maintainability.

##### Relevant Technologies & Frameworks
- Next.js for full-stack rendering.
- Tailwind CSS (configured by tailwind.config.ts) for styling.
- Typescript (noted by tsconfig.json) for type safety.
- Firebase (in “lib/firebase.ts”) for real-time or authentication needs.
- ESLint configuration and other build tools ensuring code quality and consistency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser (Client)"]:::browser

    subgraph "Frontend Application"
        %% Pages & Routing subgraph
        subgraph "Pages & Routing"
            PR_Folder["Pages & Routing"]:::pages
            AmericaPage["AmericaPage"]:::pages
            ChinaPage["ChinaPage"]:::pages
            IndiaPage["IndiaPage"]:::pages
            ChatPage["Chat Page"]:::pages
            QuizPage["Quiz Page"]:::pages
            TimelinePage["Timeline Page"]:::pages
        end

        %% Serverless API Routes subgraph
        subgraph "Serverless API Routes"
            API_Folder["API Routes"]:::api
            CheckAvatar["check-avatar-status"]:::api
            DeleteImage["delete-image"]:::api
            GenerateAvatar["generate-avatar"]:::api
            UploadImage["upload-image"]:::api
        end

        %% UI Components subgraph
        subgraph "UI Components"
            UI_Folder["UI Components"]:::components
            ChatBotComp["ChatBot Component"]:::components
            NavBarComp["NavBar Component"]:::components
            MapComponent["MapComponent"]:::components
            QuizComp["Quiz Component"]:::components
        end

        %% Data & Assets subgraph
        subgraph "Data & Assets"
            Assets["Static Assets"]:::data
            StaticData["Static Data"]:::data
        end

        %% Libraries & Utilities subgraph
        subgraph "Libraries & Utilities"
            Lib_Folder["Libraries & Utilities"]:::lib
            FirebaseModule["Firebase Module"]:::lib
            UtilsModule["Utils Module"]:::lib
        end

        %% Configuration & Build Tools subgraph
        subgraph "Configuration & Build Tools"
            NextConfig["Next.js Config"]:::config
            TailwindConfig["Tailwind Config"]:::config
            TSConfig["TS Config"]:::config
        end
    end

    %% Define Relationships (vertical flow)
    Browser -->|"accesses"| PR_Folder
    PR_Folder -->|"renders"| UI_Folder
    UI_Folder -->|"calls"| API_Folder
    API_Folder -->|"invokes"| Lib_Folder
    PR_Folder ---|"loads"| Assets
    Assets ---|"supplies"| StaticData
    Lib_Folder -->|"integrates"| FirebaseModule

    %% Configuration supports all modules
    NextConfig ---|"configures"| PR_Folder
    TailwindConfig ---|"styles"| UI_Folder
    TSConfig ---|"types"| Lib_Folder

    %% Node styling
    classDef browser fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef pages fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef api fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef components fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef data fill:#E1BEE7,stroke:#7B1FA2,stroke-width:2px;
    classDef lib fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef config fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;

    %% Click Events for Component Mappings
    click PR_Folder "https://github.com/rya23/rubix25_27_nuclitron/tree/main/frontend/app"
    click API_Folder "https://github.com/rya23/rubix25_27_nuclitron/tree/main/frontend/app/api"
    click UI_Folder "https://github.com/rya23/rubix25_27_nuclitron/tree/main/frontend/components"
    click Assets "https://github.com/rya23/rubix25_27_nuclitron/tree/main/frontend/assets"
    click StaticData "https://github.com/rya23/rubix25_27_nuclitron/tree/main/frontend/data"
    click Lib_Folder "https://github.com/rya23/rubix25_27_nuclitron/tree/main/frontend/lib"
    click FirebaseModule "https://github.com/rya23/rubix25_27_nuclitron/blob/main/frontend/lib/firebase.ts"
    click NextConfig "https://github.com/rya23/rubix25_27_nuclitron/blob/main/frontend/next.config.mjs"
    click TailwindConfig "https://github.com/rya23/rubix25_27_nuclitron/blob/main/frontend/tailwind.config.ts"
    click TSConfig "https://github.com/rya23/rubix25_27_nuclitron/blob/main/frontend/tsconfig.json"
```
