# sairishi-exe/marvel-ai-backend architecture

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

- Interactive diagram: https://gitdiagram.com/sairishi-exe/marvel-ai-backend
- Repository: https://github.com/sairishi-exe/marvel-ai-backend

## Overview

##### Project Overview and Type
- This is a backend application built using FastAPI that powers the Marvel AI Platform.
- The application is focused on processing various “assistant” and “tool” functionalities used to generate assignments, flashcards, quizzes, presentations, and more.
- It integrates with external services such as Google Cloud (Vertex AI and AI Studio) and uses Docker for containerization.
- The overall architecture is modular, with clear separations between API endpoints, service logic, specialty assistants, and tools.

##### Breaking Down the File Structure
- The top-level “app” folder is the core of the application. Inside, you have several important sub-components:
- The “api” directory: Contains the FastAPI router (router.py) and error handlers.
- The “assistants” directory: Contains various assistant implementations (organized by groups, e.g., classroom_support with further subdivisions such as co_teacher).
- The “tools” directory: Contains various tool implementations (e.g., flashcards_generator, lesson_plan_generator, multiple_choice_quiz_generator, document summarizers, etc.), each having its own core logic, prompts, tests, and metadata.
- The “services” directory: Provides the auxiliary service modules (assistant_registry, logger, schemas, tool_registry) that support application functionality.
- The “utils” directory: Contains shared utilities like authentication, document loaders, allowed file extensions, and various prompt management utilities.
- Additionally, there are configuration files for Docker, Google Cloud (app.yaml), environment variables (.env.sample), and deployment scripts (local-start.sh).

##### Main Components
a. Client & External Interfaces:
- Clients (or external users) making HTTP requests (e.g., via FastAPI’s /docs endpoint).
- External integrations such as Google Cloud’s Vertex AI.
b. API Layer:
- FastAPI application entry point (app/main.py) that routes incoming API calls to the appropriate router in app/api/router.py.
- Error handling using error_utilities.py.
c. Business Logic & Services:
- Service modules in app/services for logging, assistant and tool registries, and schema management.
- These components centrally coordinate requests between the API and the underlying functional modules.
d. Assistants and Tools Modules:
- The “assistants” directory – each assistant (like the co_teacher module within classroom_support) is a self-contained unit with its prompts, core logic, testing, etc.
- The “tools” directory – each tool (such as flashcards generator, notes generator, lesson plan generator, etc.) represents a specialized processing unit for generating educational content.
- The tools share common utilities (e.g., tool_utilities.py in the tools/utils subfolder).
e. Utility Modules:
- Helpers like authentication, file extension verification and document loaders.
f. Deployment and Environment:
- Docker: Represent the Docker container (Dockerfile and Docker run commands) that encapsulates the backend service.
- Environment configuration (.env, app.yaml) showing how critical runtime variables (like API keys and project IDs) are injected.

##### Relationships and Data Flow
- The API layer forwards validated requests to a service layer which, depending on the request, calls one or more assistant or tool modules.
- Tools and assistants might interact with shared utilities (e.g., for document loading or prompt processing) and each assistant/tool can have unit tests (indicating built-in quality validations).
- External communication with Google Cloud is abstracted within the services configuration and environment variables.

##### Architectural Patterns and Design Principles
- Modular structure: The separation into “assistants,” “tools,” “services,” and “utils” suggests a plug-and-play, modular design that allows for adding new functionalities easily.
- API Driven: Built around FastAPI, it maintains clear boundaries between the API interface and internal processing services.
- Containerized Deployment: The presence of Dockerfile, app.yaml, and associated deployment scripts underscores the portability and encapsulation of the runtime environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client and Deployment
    subgraph "External Interfaces"
        Client["Clients"]:::external
        GC["Google Cloud Vertex AI"]:::external
    end

    subgraph "Deployment & Environment Configuration"
        Deploy["Deployment & Configuration"]:::deployment
    end

    %% API Layer
    subgraph "API Layer"
        FASTAPI["\"FastAPI Entry Point\""]:::api
        API_Router["\"API Router & Error Utilities\""]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        ASRegistry["\"assistant_registry\""]:::service
        Logger["\"logger\""]:::service
        Schemas["\"schemas\""]:::service
        ToolRegistry["\"tool_registry\""]:::service
    end

    %% Assistants Modules
    subgraph "Assistants Modules"
        CoTeacher["\"Co-Teacher Assistant\""]:::assistant
        CoTeacherCore["\"Co-Teacher Core Logic\""]:::assistant
    end

    %% Tools Modules
    subgraph "Tools Modules"
        Flashcards["\"Flashcards Generator\""]:::tool
        LessonPlan["\"Lesson Plan Generator\""]:::tool
        MCQuiz["\"MC Quiz Generator\""]:::tool
        Presentation["\"Presentation Generator\""]:::tool
        PresentationOutline["\"Presentation Outline\""]:::tool
        PresentationSlide["\"Presentation Slide\""]:::tool
        OtherTools["\"Other Tools Modules\""]:::tool
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Utils["\"Shared Utilities\""]:::utility
    end

    %% Data Flow Connections
    Client -->|"HTTP Request"| FASTAPI
    Deploy --> FASTAPI
    FASTAPI -->|"Routes"| API_Router
    API_Router -->|"Delegates to"| ASRegistry
    API_Router -->|"Delegates to"| Logger
    API_Router -->|"Delegates to"| Schemas
    API_Router -->|"Delegates to"| ToolRegistry
    ASRegistry -->|"Triggers Assistant"| CoTeacher
    Logger --> CoTeacher
    Schemas --> MCQuiz
    ToolRegistry --> Flashcards
    ToolRegistry --> LessonPlan
    ToolRegistry --> MCQuiz
    ToolRegistry --> Presentation
    ToolRegistry --> OtherTools
    %% Connect Service modules to External integration
    ToolRegistry -->|"Calls APIs"| GC

    %% Connect Assistants and Tools to Utilities
    CoTeacher -->|"Uses"| Utils
    CoTeacherCore -->|"Uses"| Utils
    Flashcards -->|"Uses"| Utils
    LessonPlan -->|"Uses"| Utils
    MCQuiz -->|"Uses"| Utils
    Presentation -->|"Uses"| Utils
    PresentationOutline -->|"Uses"| Utils
    PresentationSlide -->|"Uses"| Utils
    OtherTools -->|"Uses"| Utils

    %% Internal relationships within Assistants and Tools
    CoTeacher -->|"Incorporates"| CoTeacherCore
    Presentation -->|"Updated By"| PresentationOutline
    Presentation -->|"Updated By"| PresentationSlide

    %% Click Events
    click FASTAPI "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/main.py"
    click API_Router "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/api/router.py"
    click ASRegistry "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/services/assistant_registry.py"
    click Logger "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/services/logger.py"
    click Schemas "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/services/schemas.py"
    click ToolRegistry "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/services/tool_registry.py"
    click CoTeacher "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/assistants/classroom_support/co_teacher/assistant.py"
    click CoTeacherCore "https://github.com/sairishi-exe/marvel-ai-backend/blob/Develop/app/assistants/classroom_support/co_teacher/core.py"
    click Flashcards "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/tools/flashcards_generator"
    click LessonPlan "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/tools/lesson_plan_generator"
    click MCQuiz "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/tools/multiple_choice_quiz_generator"
    click Presentation "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/tools/presentation_generator"
    click PresentationOutline "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/tools/presentation_generator_updated/outline_generator"
    click PresentationSlide "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/tools/presentation_generator_updated/slide_generator"
    click Utils "https://github.com/sairishi-exe/marvel-ai-backend/tree/Develop/app/utils"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef service fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef assistant fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef tool fill:#DA70D6,stroke:#000,stroke-width:2px;
    classDef utility fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FF6347,stroke:#000,stroke-width:2px;
```
