# democratiseresearch/saral architecture

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

- Interactive diagram: https://gitdiagram.com/democratiseresearch/saral
- Repository: https://github.com/democratiseresearch/saral

## Overview

##### Project type and purpose
- SARAL AI is a full-stack web application that automates converting research papers into educational videos.
- Frontend: React + Tailwind CSS (single-page app)
- Backend: Python FastAPI (monolithic service with modular “services” layers)

##### File structure
- Top-level directories:
– backend/ (FastAPI app, services, routes, utils, temp file store)
– frontend/ (React app, components, pages, contexts, hooks)
- backend/app/
– routes/ define API endpoints (/papers, /scripts, /slides, /media, /images)
– services/ implement discrete processing steps (arxiv_scraper, latex_processor, script_generator, beamer_generator, tts_service, video_service, storage_manager)
– utils/ helper functions (e.g., LaTeX→images)
– dependencies/ manage auth and session injection
- frontend/src/
– components/ (forms, workflow, navigation, common UI)
– contexts/ manage global state (API config, auth, workflow progress)
– services/api.js wraps REST calls to backend
– pages/ represent each step of the pipeline

##### README for additional insights
- Workflow stages are explicitly described:
1. API key config
2. Paper upload (LaTeX ZIP or arXiv link)
3. Script generation (AI via Google Gemini)
4. Slide generation (beamer + extracted figures)
5. Video production (TTS + FFmpeg)
- External dependencies: poppler-utils, pdflatex, FFmpeg, Google Gemini, Sarvam TTS

a. Main components
– User Browser (React SPA)
– Frontend App (UI, state management, service calls)
– Backend API Gateway (FastAPI)
– Processing Modules (services folder):
- ArXiv Scraper
- LaTeX Processor
- Script Generator
- Slide (Beamer) Generator
- TTS Service
- Video Synthesizer
- Storage Manager
– Temporary File Store (backend/temp/)
– External Services: ArXiv, Google Gemini API, Sarvam TTS API
b. Relationships & data flow
1. User uploads paper or inputs arXiv URL in Frontend
2. Frontend calls backend /papers endpoint
3. Backend invokes ArXiv Scraper or LaTeX Processor → stores raw assets in temp
4. Frontend requests script via /scripts → backend calls Script Generator (Google Gemini)
5. Frontend requests slides via /slides → backend calls Beamer Generator + utils → PDF + PNG slides
6. Frontend requests media via /media → backend calls TTS Service + Video Synthesizer (FFmpeg)
7. Storage Manager collects final media and returns download URLs to Frontend
c. Architectural patterns & principles
– Layered architecture (API → services → utils → storage)
– Dependency injection for auth & session (FastAPI dependencies)
– Single Responsibility per service module
d. Key technologies & libraries
– Frontend: React, Tailwind CSS, React Context, REST
– Backend: FastAPI, Pydantic models, Python services
– Processing: pdflatex, poppler-utils, FFmpeg
– AI: Google Gemini API, Sarvam TTS

##### Detail
- Temp directory as a staging area between modules
- How the Storage Manager interfaces with the file system and returns URLs
- Auth flow (AuthContext ↔ /auth endpoints) if needed

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    Browser["User Browser"]:::frontend

    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        FE["Frontend App"]:::frontend
        Components["UI Components"]:::frontend
        Pages["Pages (Workflow Steps)"]:::frontend
        Contexts["State Management Contexts"]:::frontend
        APIService["API Service Wrapper"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        direction TB
        APIGateway["API Gateway (FastAPI)"]:::backend

        subgraph "Routes"
            direction TB
            Papers["POST /papers"]:::backend
            Scripts["GET /scripts"]:::backend
            Slides["GET /slides"]:::backend
            Media["GET /media"]:::backend
            Images["GET /images"]:::backend
            Auth["Auth Endpoints"]:::backend
        end

        subgraph "Services"
            direction TB
            Arxiv["ArXiv Scraper"]:::backend
            Latex["LaTeX Processor"]:::backend
            ScriptGen["Script Generator"]:::backend
            Beamer["Beamer Generator"]:::backend
            TTS["Text-to-Speech Service"]:::backend
            Video["Video Synthesizer"]:::backend
            StorageM["Storage Manager"]:::backend
        end

        subgraph "Utils"
            direction TB
            PDFProc["PDF Processing Utility"]:::backend
            LatexImgs["LaTeX→Image Utility"]:::backend
        end

        TempStore["Temp File Store"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ArxivAPI["ArXiv API"]:::external
        GeminiAPI["Google Gemini API"]:::external
        TTSAPI["Sarvam TTS API"]:::external
    end

    %% Connections - Frontend to Backend
    Browser -->|"interacts with"| Components
    Components -->|uses| FE
    FE -->|calls REST| APIService
    APIService -->|POST /papers| APIGateway
    APIService -->|GET /scripts| APIGateway
    APIService -->|GET /slides| APIGateway
    APIService -->|GET /media| APIGateway
    APIService -->|GET /images| APIGateway
    Contexts -->|provide auth/config| FE

    %% API Gateway to Routes
    APIGateway --> Papers
    APIGateway --> Scripts
    APIGateway --> Slides
    APIGateway --> Media
    APIGateway --> Images
    APIGateway --> Auth

    %% Papers Flow
    Papers -->|"scrape or upload"| Arxiv
    Papers -->|"process LaTeX"| Latex
    Arxiv -->|"store raw assets"| TempStore
    Latex -->|"store processed assets"| TempStore
    Arxiv --> ArxivAPI
    LatexImgs --> TempStore

    %% Script Flow
    Scripts --> ScriptGen
    ScriptGen -->|calls Gemini| GeminiAPI
    ScriptGen --> TempStore

    %% Slide Flow
    Slides --> Beamer
    Beamer --> PDFProc
    Beamer --> LatexImgs
    PDFProc --> TempStore
    LatexImgs --> TempStore

    %% Media Flow
    Media --> TTS
    TTS -->|calls TTS API| TTSAPI
    TTS --> TempStore
    Media --> Video
    Video -->|uses FFmpeg| TempStore
    Video --> TempStore

    %% Storage Manager
    StorageM --> TempStore
    APIGateway --> StorageM
    StorageM -->|returns URLs| APIService
    APIService --> Browser

    %% Click Events
    click Components "https://github.com/democratiseresearch/saral/tree/main/frontend/src/components"
    click Pages "https://github.com/democratiseresearch/saral/tree/main/frontend/src/pages"
    click Contexts "https://github.com/democratiseresearch/saral/tree/main/frontend/src/contexts"
    click APIService "https://github.com/democratiseresearch/saral/blob/main/frontend/src/services/api.js"
    click FE "https://github.com/democratiseresearch/saral/tree/main/frontend/src"
    click APIGateway "https://github.com/democratiseresearch/saral/blob/main/backend/app/main.py"
    click Papers "https://github.com/democratiseresearch/saral/tree/main/backend/app/routes"
    click Scripts "https://github.com/democratiseresearch/saral/tree/main/backend/app/routes"
    click Slides "https://github.com/democratiseresearch/saral/tree/main/backend/app/routes"
    click Media "https://github.com/democratiseresearch/saral/tree/main/backend/app/routes"
    click Images "https://github.com/democratiseresearch/saral/tree/main/backend/app/routes"
    click Auth "https://github.com/democratiseresearch/saral/tree/main/backend/app/auth"
    click Auth "https://github.com/democratiseresearch/saral/tree/main/backend/app/dependencies"
    click Arxiv "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/arxiv_scraper.py"
    click Latex "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/latex_processor.py"
    click ScriptGen "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/script_generator.py"
    click Beamer "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/beamer_generator.py"
    click TTS "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/tts_service.py"
    click Video "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/video_service.py"
    click StorageM "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/storage_manager.py"
    click PDFProc "https://github.com/democratiseresearch/saral/blob/main/backend/app/services/pdf_processor.py"
    click LatexImgs "https://github.com/democratiseresearch/saral/blob/main/backend/app/utils/latex_to_images.py"
    click TempStore "https://github.com/democratiseresearch/saral/tree/main/backend/temp"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D6F5D6,stroke:#028a0f,color:#028a0f
    classDef storage fill:#F0F0F0,stroke:#555555,color:#555555
    classDef external fill:#FFE0B2,stroke:#e65100,color:#e65100
```
