# sprwoo/2blue2brown architecture

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

- Interactive diagram: https://gitdiagram.com/sprwoo/2blue2brown
- Repository: https://github.com/sprwoo/2blue2brown

## Overview

##### Main Components
a. Frontend Application:
- Built with Next.js and TypeScript (files like page.tsx, layout.tsx, and several component *.tsx files).
- Handles user interactions (chat window, login, general layout, etc.).
- Integrates with Supabase (see frontend/lib/supabaseClient.ts) for authentication or data fetching.

b. Backend Application:
- API Layer: Contains the “api” subfolder in backend/app/api, which includes environment configurations and the manimations module for generating animated content.
- Controllers: Found in backend/app/controllers, include files like manim_maker, video_maker, voiceover_maker, etc., which process business logic.
- Langgraph Nodes: The backend/app/langgraph_nodes directory encapsulates components handling conversation flow, decisions, and expected chat responses.
- Routes: The backend/app/routes folder defines endpoints handling different tasks (e.g., session management, uploads, chat routes).
- Services: The backend/app/services directory abstracts integrations such as with Supabase (supabase.py) or handling posts (post.py).
- Supporting Modules: The manim animations (inside backend/app/api/manimations and backend/generated_manim) play a role in rendering animated content, which is central to the chatbot’s enhanced responses.
- Testing Components: Located in backend/app/tests which ensure functionalities (e.g., test_llms.py).

##### Relationships and Interactions Between Components
- Frontend to Backend Communication:
- The frontend interacts with the backend via API calls (REST endpoints defined in the routes folder) for initiating chat sessions, uploading inputs, and receiving processed responses.
- Backend Internal Communication:
- The API layer forwards requests to appropriate controllers. For example, chat inputs might be routed to controllers like prompts.py or langgraph_flow.py.
- The controllers call specific modules in langgraph_nodes for decision-making and routing of tasks (text processing or chat response generation).
- Animation generation: Some controllers trigger the “manim_maker.py” or “to_manim2.py” scripts which then communicate with the manim animations module to create visual content.
- Voiceover/Video Generation: Similar flows occur for video/voiceover creation functions (look at voiceover_maker.py and video_maker.py).
- The services layer handles interactions with external systems such as Supabase, ensuring data persistence, user management, or file storage.
- External Dependencies:
- Supabase is integrated on both the frontend (via a client) and backend (via services) for external data storage or authentication.
- Environment variables (.env files in various locations) should be indicated as configurations that affect multiple components.

##### Architectural Patterns and Design Principles
- Modular design separating concerns: clear segmentation between API handling, business logic (controllers), and specialized tasks (animations, video/voiceover generation).
- Layering: Different layers for presentation (frontend), application logic (controllers/routes), and integrations (services).
- Extensibility: The structure (e.g., langgraph_nodes) implies that new types of nodes or components can be added to extend chatbot capabilities.
- Use of environment-based configuration for flexibility and security.

##### Final Recommendations
- Incorporate any additional annotations that might help illustrate the purpose of specialized modules, for example how the chatbot leverages notes consolidation and concept learning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Configuration
    EnvConfig[".env Configuration"]:::config

    %% Frontend Layer
    subgraph "Frontend Layer"
        F_Page["Page (Next.js)"]:::frontend
        F_Layout["Layout (Next.js)"]:::frontend
        F_ChatWindow["ChatWindow (Component)"]:::frontend
        F_SupabaseClient["Supabase Client"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        %% API Layer Subgraph
        subgraph "API Layer"
            B_API["API Layer"]:::api
            B_ManimationsAPI["Manimations API"]:::api
            B_ToManim["To Manim Script"]:::api
        end

        %% Routes Subgraph
        subgraph "Routes"
            B_ChatRoutes["Chat Routes"]:::route
            B_SessionRoutes["Session Routes"]:::route
            B_UploadRoutes["Upload Routes"]:::route
        end

        %% Controllers Subgraph
        subgraph "Controllers"
            C_ManimMaker["Manim Maker"]:::controller
            C_VideoMaker["Video Maker"]:::controller
            C_VoiceoverMaker["Voiceover Maker"]:::controller
            C_Prompts["Prompts"]:::controller
            C_LanggraphFlow["Langgraph Flow"]:::controller
        end

        %% Langgraph Nodes Subgraph
        subgraph "Langgraph Nodes"
            LN_ChatResponse["Chat Response"]:::nodes
            LN_Decision["Decision"]:::nodes
            LN_Director["Director"]:::nodes
        end

        %% Services Subgraph
        subgraph "Services"
            S_SupabaseService["Supabase Service"]:::service
            S_PostService["Post Service"]:::service
        end

        %% Animation Modules Subgraph
        subgraph "Animation Modules"
            A_ManimModule["Manim Module"]:::animation
            A_AltManimModule["Alternate Manim Module"]:::animation
        end

        %% Testing Subgraph
        subgraph "Testing"
            T_BackendTests["Backend Tests"]:::test
        end
    end

    %% Connections from Configuration to Layers
    EnvConfig -->|"configures"| F_Page
    EnvConfig -->|"configures"| B_API

    %% Frontend to Backend communication
    F_ChatWindow -->|"API_Call"| B_ChatRoutes
    F_SupabaseClient -->|"Auth_Request"| S_SupabaseService

    %% API Layer to Controllers
    B_API -->|"Forward_Request"| C_Prompts
    B_ManimationsAPI -->|"Manim_Request"| C_ManimMaker
    B_ToManim -->|"Manim_Request2"| C_ManimMaker

    %% Routes to Controllers
    B_ChatRoutes -->|"Request_Routing"| C_Prompts
    B_SessionRoutes -->|"Request_Routing"| C_Prompts
    B_UploadRoutes -->|"Request_Routing"| C_Prompts

    %% Controllers internal communications
    C_Prompts -->|"Chat_Processing"| LN_ChatResponse
    C_LanggraphFlow -->|"Chat_Flow"| LN_Decision
    C_Prompts -->|"Flow_Update"| LN_Director
    C_ManimMaker -->|"Animation_Generation"| A_ManimModule
    C_VideoMaker -->|"Media_Processing"| S_SupabaseService
    C_VoiceoverMaker -->|"Media_Processing"| S_SupabaseService
    C_LanggraphFlow -->|"Post_Handling"| S_PostService

    %% Controllers to Testing
    C_Prompts -->|"Verification"| T_BackendTests

    %% Click Events for Frontend
    click F_Page "https://github.com/sprwoo/2blue2brown/blob/main/frontend/app/page.tsx"
    click F_Layout "https://github.com/sprwoo/2blue2brown/blob/main/frontend/app/layout.tsx"
    click F_ChatWindow "https://github.com/sprwoo/2blue2brown/blob/main/frontend/components/ChatWindow.tsx"
    click F_SupabaseClient "https://github.com/sprwoo/2blue2brown/blob/main/frontend/lib/supabaseClient.ts"

    %% Click Events for Backend API Layer
    click B_API "https://github.com/sprwoo/2blue2brown/tree/main/backend/app/api"
    click B_ManimationsAPI "https://github.com/sprwoo/2blue2brown/tree/main/backend/app/api/manimations"
    click B_ToManim "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/api/to_manim2.py"

    %% Click Events for Controllers
    click C_ManimMaker "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/controllers/manim_maker.py"
    click C_VideoMaker "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/controllers/video_maker.py"
    click C_VoiceoverMaker "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/controllers/voiceover_maker.py"
    click C_Prompts "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/controllers/prompts.py"
    click C_LanggraphFlow "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/controllers/langgraph_flow.py"

    %% Click Events for Langgraph Nodes
    click LN_ChatResponse "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/langgraph_nodes/chat_response.py"
    click LN_Decision "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/langgraph_nodes/decision.py"
    click LN_Director "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/langgraph_nodes/director.py"

    %% Click Events for Routes
    click B_ChatRoutes "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/routes/chat_routes.py"
    click B_SessionRoutes "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/routes/session_routes.py"
    click B_UploadRoutes "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/routes/upload_routes.py"

    %% Click Events for Services
    click S_SupabaseService "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/services/supabase.py"
    click S_PostService "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/services/post.py"

    %% Click Events for Animation Modules
    click A_ManimModule "https://github.com/sprwoo/2blue2brown/blob/main/backend/generated_manim/manim.py"
    click A_AltManimModule "https://github.com/sprwoo/2blue2brown/blob/main/backend/generated_manin/manim.py"

    %% Click Event for Testing
    click T_BackendTests "https://github.com/sprwoo/2blue2brown/blob/main/backend/app/tests/test_llms.py"

    %% Styles
    classDef frontend fill:#C6E2FF,stroke:#1F77B4,stroke-width:2px;
    classDef api fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef controller fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px;
    classDef nodes fill:#F0E68C,stroke:#BDB76B,stroke-width:2px;
    classDef route fill:#D8BFD8,stroke:#DA70D6,stroke-width:2px;
    classDef service fill:#98FB98,stroke:#32CD32,stroke-width:2px;
    classDef animation fill:#FFE4E1,stroke:#FF6347,stroke-width:2px;
    classDef test fill:#F5DEB3,stroke:#D2691E,stroke-width:2px;
    classDef config fill:#E0FFFF,stroke:#20B2AA,stroke-width:2px;
```
