# bhaumil111/paperparser architecture

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

- Interactive diagram: https://gitdiagram.com/bhaumil111/paperparser
- Repository: https://github.com/bhaumil111/paperparser

## Overview

##### Project type and purpose
- PaperParser is a full-stack web application whose purpose is to ingest academic PDF papers and output either audio podcasts (via TTS) or PowerPoint slide decks summarizing key points.

##### File structure
- Top-level directories:
- backend/ – Express.js REST API + Python scripts for PPT generation & helper utilities
- frontend/ – Next.js/TypeScript UI, integrates with Supabase/Firebase for auth & storage
- Key backend subfolders:
- python-scripts/ – handles PPT creation, image extraction, and podcast generation (edge-tts or Google TTS)
- routes/ – upload endpoints used by the frontend
- Key frontend files:
- app/ & components/ – React pages and UI primitives
- lib/ – API abstraction for calling backend, plus Supabase/Firebase configuration
- COMPLETE_SUPABASE_SETUP.md, FIREBASE_SETUP.md – indicate optional auth/storage backends

##### README
- Confirms architecture: Next.js frontend, Node/Express backend, optional Python dependencies, TTS & PDF parsing libraries, PPTX generator.
- User flow: upload → choose format → process → download/stream.

a. Main components
- User Interface (Next.js frontend)
- Authentication & File Storage (Supabase/Firebase)
- API Gateway (Express.js server)
- Processing Engine (Node modules + Python scripts)
- External Services: PDF parsing library, TTS provider (edge-tts/Google TTS)
- Storage: Generated PPTX/audio files (could be local or cloud storage)
b. Relationships & data flow
1. User uploads PDF via Next.js UI
2. Frontend authenticates user via Supabase/Firebase and stores the PDF
3. Frontend calls Express API /uploads endpoint
4. Express saves file, invokes PDF parsing library to extract text
5. Depending on user choice:
– For PPT: Express calls Python script (generate_ppt.py) → PPTX file returned
– For Podcast: Express passes text to edge-tts/Google TTS module → audio file generated
6. Processed files are stored back to storage (Supabase bucket or local FS)
7. Frontend polls or streams the result for user download/stream
c. Architectural patterns & design principles
– Clear separation of concerns: UI layer, API layer, processing layer
– Micro-workflow for each output format, pluggable via Python scripts or Node modules
– Stateless RESTful endpoints; heavy lifting done in ephemeral worker processes
– Optional externalized auth/storage via Supabase or Firebase
d. Key technologies
– Next.js & React (UI)
– TypeScript (static typing)
– Express.js on Node.js (API)
– Python (PPTX generation scripts)
– edge-tts / Google TTS (podcast)
– PDF parsing library (backend)
– Supabase / Firebase (auth + storage buckets)

##### Elements
- Rectangles for each component: “Next.js UI,” “Express API,” “Python PPT Generator,” “TTS Engine,” “Supabase Storage,” etc.
- User → UI → API endpoints → processing modules → storage → UI → User
- Frontend (blue)
- Backend/API (green)
- Workers (orange)
- External services & storage (purple)
- Parallelograms for user interface
- Rectangles for servers/processors

##### Detailed guidance
- Every processing step as a separate node to reflect the Python vs Node pathway
- Error-handling or fallback paths if desired (e.g., Python script failure → API error response)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Tier
    subgraph "Presentation Tier"
        User((User)):::external
        UI["Next.js UI<br/>(frontend/app, frontend/components)"]:::frontend
        Auth["Auth & File Storage<br/>(Supabase/Firebase)"]:::frontend
    end

    %% Application Tier
    subgraph "Application Tier"
        API["Express API Gateway<br/>(Express.js + pdf-parser)"]:::backend
    end

    %% Processing Engines
    subgraph "Processing Engines"
        PPT["Python PPT Generator"]:::workers
        TTS["Podcast TTS Engine"]:::workers
    end

    %% Data & Services Tier
    subgraph "Data & Services Tier"
        PDFParse["PDF Parsing Library"]:::external
        TTSService["TTS Provider"]:::external
        Storage["Storage Buckets<br/>(Supabase/Firebase)"]:::external
    end

    %% Configurations
    subgraph "Configurations"
        BEPkg["backend/package.json"]:::backend
        BELock["backend/package-lock.json"]:::backend
        Req["backend/requirements.txt"]:::backend
        Docker["backend/Dockerfile"]:::backend
        FEPkg["frontend/package.json"]:::frontend
        FELock["frontend/pnpm-lock.yaml"]:::frontend
        NextCfg["frontend/next.config.mjs"]:::frontend
        TSJson["frontend/tsconfig.json"]:::frontend
        Tailwind["frontend/tailwind.config.ts"]:::frontend
        Postcss["frontend/postcss.config.mjs"]:::frontend
    end

    %% Connections
    User --> UI
    UI --> Auth
    UI -->|HTTP REST| API
    API -->|Extract text| PDFParse
    PDFParse --> API
    API -->|Invoke PPT| PPT
    PPT -->|Generate PPTX| Storage
    API -->|Invoke TTS| TTS
    TTS -->|Audio file| Storage
    Storage --> UI

    %% Click Events
    click UI "https://github.com/bhaumil111/paperparser/tree/main/frontend/app/"
    click UI "https://github.com/bhaumil111/paperparser/tree/main/frontend/components/"
    click Auth "https://github.com/bhaumil111/paperparser/blob/main/frontend/lib/supabase.ts"
    click Auth "https://github.com/bhaumil111/paperparser/blob/main/frontend/lib/supabase-safe.ts"
    click Auth "https://github.com/bhaumil111/paperparser/blob/main/frontend/lib/firebase.ts"
    click Auth "https://github.com/bhaumil111/paperparser/blob/main/frontend/COMPLETE_SUPABASE_SETUP.md"
    click Auth "https://github.com/bhaumil111/paperparser/blob/main/frontend/FIREBASE_SETUP.md"
    click Auth "https://github.com/bhaumil111/paperparser/blob/main/frontend/SUPABASE_SETUP.md"
    click API "https://github.com/bhaumil111/paperparser/blob/main/backend/server.js"
    click API "https://github.com/bhaumil111/paperparser/blob/main/backend/routes/uploads.js"
    click PDFParse "https://github.com/bhaumil111/paperparser/blob/main/backend/routes/uploads.js"
    click PPT "https://github.com/bhaumil111/paperparser/blob/main/backend/python-scripts/generate_ppt.py"
    click PPT "https://github.com/bhaumil111/paperparser/blob/main/backend/python-scripts/helper/image_extractor.py"
    click PPT "https://github.com/bhaumil111/paperparser/blob/main/backend/python-scripts/helper/ppt_maker.py"
    click PPT "https://github.com/bhaumil111/paperparser/blob/main/backend/generate_ppt.py"
    click PPT "https://github.com/bhaumil111/paperparser/blob/main/backend/Template3-ppt.pptx"
    click TTS "https://github.com/bhaumil111/paperparser/blob/main/backend/python-scripts/podcast/generate_podcast.py"
    click TTS "https://github.com/bhaumil111/paperparser/blob/main/backend/python-scripts/podcast/voice.py"
    click TTS "https://github.com/bhaumil111/paperparser/blob/main/backend/python-scripts/podcast/gemini_config.py"
    click BEPkg "https://github.com/bhaumil111/paperparser/blob/main/backend/package.json"
    click BELock "https://github.com/bhaumil111/paperparser/blob/main/backend/package-lock.json"
    click Req "https://github.com/bhaumil111/paperparser/blob/main/backend/requirements.txt"
    click Docker "https://github.com/bhaumil111/paperparser/tree/main/backend/Dockerfile"
    click FEPkg "https://github.com/bhaumil111/paperparser/blob/main/frontend/package.json"
    click FELock "https://github.com/bhaumil111/paperparser/blob/main/frontend/pnpm-lock.yaml"
    click NextCfg "https://github.com/bhaumil111/paperparser/blob/main/frontend/next.config.mjs"
    click TSJson "https://github.com/bhaumil111/paperparser/blob/main/frontend/tsconfig.json"
    click Tailwind "https://github.com/bhaumil111/paperparser/blob/main/frontend/tailwind.config.ts"
    click Postcss "https://github.com/bhaumil111/paperparser/blob/main/frontend/postcss.config.mjs"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef workers fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef external fill:#e1bee7,stroke:#4a148c,color:#4a148c
```
