# marvelai-org/marvel-platform architecture

> Architecture diagram of the GitHub repository marvelai-org/marvel-platform, 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/marvelai-org/marvel-platform
- Repository: https://github.com/marvelai-org/marvel-platform

## Overview

##### Main Components Identification
- Frontend Application: This is implemented in Next.js and React. It’s visible from the presence of pages (e.g., pages/index.jsx, pages/signin, pages/onboarding) and numerous UI components and layouts. It connects with Firebase for hosting and operates the interactive elements for teachers.
- Backend Services (Firebase Functions): The /functions folder contains cloud functions (e.g., signUpUser, createChatSession, communicator) that handle user management, chat sessions, and secure, compute-intensive tasks.
- Firebase Services:
- Firestore Database to store data such as users, chat sessions, and tool usage history.
- Firebase Hosting to serve the Next.js frontend.
- Emulators for local development (as explained in the README).
- External AI Endpoints: Although managed in another repository, the frontend sends tool requests (like “Quizify” and “Flashcard Generator”) to external AI services.
- Auxiliary Modules:
- Redux Toolkit for state management (visible in libs/redux) and additional hooks, providers, and constants.
- Various UI components grouped in directories (components, templates, tools) that form the interactive interface.

##### Relationships and Interactions
- The Frontend interacts with both Firebase-hosted backend services and direct AI endpoints:
- Firebase Functions: Manage sensitive tasks, sign-ups, chat session creation, and act as a proxy between the frontend and AI.
- Firestore DB: Receives read/write requests from both the frontend and functions.
- External AI Endpoints: The frontend sends tool requests directly to these endpoints (via defined services in tools/libs/services or similar modules).
- Data flows should show user actions (login/sign-up, chat, tool usage) generating events that are handled by both the UI and passed to the backend for data persistence and interactions with AI services.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear separation between presentation (React components/templates) and business logic (Firebase functions and Redux).
- Serverless Backend: Firebase Functions provide a modular, scalable approach for backend processing.
- Microservices Approach: Although not multiple services in the same repository, the functions represent decoupled backend processes, and the external AI endpoints act as independent services.
- Local & Cloud Deployment Options: The architecture supports both full local development (with Firebase emulators) and production deployments connecting to live Firebase projects.

##### Elements
- Clear labels for every component (e.g., "Next.js Frontend", "Firebase Functions", "Firestore", "External AI Endpoint").
- From the user's browser interacting with the Next.js app.
- From the frontend to Firebase Functions (for secure operations) and directly to external AI endpoints (for tool processing).
- Data flow between the backend and Firestore.
- Rectangles for application modules (frontend, functions).
- Optionally, include a section that illustrates the local development environment with emulator interactions.

Final Note:

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Browser"]:::external

    subgraph "Frontend Layer"
        FE_Next["Next.js Frontend"]:::frontend
        FE_Pages["Pages (pages)"]:::frontend
        FE_Components["UI Components (components)"]:::frontend
        FE_Templates["Templates (templates)"]:::frontend
        FE_Layouts["Layouts (layouts)"]:::frontend
        FE_Tools["Tools Interface (tools)"]:::frontend
        FE_Redux["Redux Toolkit (libs/redux)"]:::frontend
        FE_FirebaseClient["Firebase Client (libs/firebase)"]:::frontend
    end

    subgraph "Backend Layer"
        FB_Functions["Firebase Functions (functions)"]:::backend
        FB_Config["Firebase Config (firebase.json,firestore.rules,firestore.indexes.json)"]:::backend
        FB_Firestore["Firestore Database"]:::database
        FB_Services["Firebase Hosting & Emulators"]:::backend
    end

    External["External AI Endpoints"]:::external

    %% User to Frontend
    User -->|"accesses"| FE_Next

    %% Frontend internal components linked to main Next.js app
    FE_Pages --> FE_Next
    FE_Components --> FE_Next
    FE_Templates --> FE_Next
    FE_Layouts --> FE_Next
    FE_Tools --> FE_Next
    FE_Redux --> FE_Next
    FE_FirebaseClient --> FE_Next

    %% Frontend interactions with Backend and External services
    FE_Next -->|"secureRequests"| FB_Functions
    FE_Next -->|"toolRequests"| External

    %% Backend interactions
    FB_Functions -->|"dataFlow"| FB_Firestore
    FB_Functions --> FB_Services
    FB_Config -->|"configures"| FB_Services

    %% Click Events
    click FE_Pages "https://github.com/marvelai-org/marvel-platform/tree/develop/pages"
    click FE_Components "https://github.com/marvelai-org/marvel-platform/tree/develop/components"
    click FE_Templates "https://github.com/marvelai-org/marvel-platform/tree/develop/templates"
    click FE_Layouts "https://github.com/marvelai-org/marvel-platform/tree/develop/layouts"
    click FE_Tools "https://github.com/marvelai-org/marvel-platform/tree/develop/tools"
    click FB_Functions "https://github.com/marvelai-org/marvel-platform/tree/develop/functions"
    click FB_Config "https://github.com/marvelai-org/marvel-platform/blob/develop/firebase.json"
    click FE_Redux "https://github.com/marvelai-org/marvel-platform/tree/develop/libs/redux"
    click FE_FirebaseClient "https://github.com/marvelai-org/marvel-platform/tree/develop/libs/firebase"
    click External "https://github.com/marvelai-org/marvel-platform/blob/develop/tools/libs/services/submitPrompt.js"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px;
    classDef database fill:#ffeb99,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
```
