# hkuds/paper2slides architecture

> Architecture diagram of the GitHub repository hkuds/paper2slides, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hkuds/paper2slides
- Repository: https://github.com/hkuds/paper2slides

## Overview

1. **Two entry paths, one core engine**
   - Paper2Slides has a shared Python core used by both the CLI and the web app.
   - The CLI entry point is `paper2slides/main.py` / `__main__.py`.
   - The web interface is split into a Python API backend in `api/server.py` and a React frontend in `frontend/`.

2. **The main architectural boundary is the 4-stage document-to-slides pipeline**
   - `paper2slides/core/pipeline.py` orchestrates four stages under `paper2slides/core/stages/`:
     - `rag_stage.py`
     - `summary_stage.py`
     - `plan_stage.py`
     - `generate_stage.py`
   - This pipeline is the central data flow: raw documents in, slide/poster artifacts out.

3. **Stage 1: ingestion + retrieval indexing**
   - `paper2slides/raganything/` handles parsing and RAG-style indexing for documents.
   - This is the subsystem that turns source files into searchable, structured content.
   - It supports the “normal” mode described in the README, where the document is indexed before later stages consume it.

4. **Stage 2: content extraction and normalization**
   - `paper2slides/summary/` extracts paper structure, figures, tables, and cleans extracted content.
   - The `extractors/` subpackage contains specialized figure/table handling.
   - Outputs here are the structured content map and human-readable summary used downstream.

5. **Stage 3: presentation planning**
   - `paper2slides/generator/content_planner.py` converts the extracted content into a slide/poster blueprint.
   - Prompt templates in `paper2slides/prompts/content_planning.py` shape how the LLM plans layout and sequencing.
   - This stage is where style, length, and density choices are translated into a presentation structure.

6. **Stage 4: visual generation**
   - `paper2slides/generator/image_generator.py` produces the final slide/poster images.
   - Image generation is provider-driven: the README mentions OpenRouter by default and Google Gemini as an alternative.
   - This stage is the output boundary that creates the actual presentation assets, usually as images and a final PDF.

7. **Checkpointing is a first-class subsystem**
   - `paper2slides/core/state.py` manages resume/restart state.
   - The pipeline persists stage checkpoints such as `checkpoint_rag.json`, `checkpoint_summary.json`, and `checkpoint_plan.json`.
   - Output directories also store `state.json`, timestamps, generated slide images, and the final PDF.
   - This makes the architecture resumable across interruptions and allows stage-by-stage regeneration.

8. **The web backend is a thin service layer over the pipeline**
   - `api/server.py` likely exposes the core functionality as API endpoints for upload, config, progress, and output retrieval.
   - The frontend components suggest the UI is organized around file upload, workflow status, configuration, history, conversation/chat, and slide preview.
   - In architectural terms, the backend adapts the core pipeline for interactive use; the frontend is a separate presentation layer.

9. **Frontend structure reflects interactive workflow control**
   - `frontend/src/components/` includes `FileUpload`, `ConfigPanel`, `WorkflowPanel`, `HistoryPanel`, `SlidePreview`, `MessageList`, `MessageInput`, and `Sidebar`.
   - This indicates the UI is not just a viewer; it orchestrates generation settings, monitors progress, and previews results.
   - Built with React, Vite, and Tailwind CSS.

10. **Configuration and secrets are externalized**
   - Runtime settings come from `paper2slides/.env` and `paper2slides/.env.example`.
   - Key configurable areas include the image generation provider, API keys, model names, and base URLs.
   - This matters architecturally because the generation layer depends on external LLM/image APIs rather than local rendering only.

11. **Deployment is supported in both local and containerized forms**
   - `scripts/start.sh`, `start_backend.sh`, and `start_frontend.sh` provide local process orchestration.
   - `docker/docker-compose.yml`, `Dockerfile.backend`, `Dockerfile.frontend`, and `nginx.conf` define a containerized deployment path.
   - So the system can run as separate services or as a combined container stack.

12. **Repository outputs are organized around project/session identity**
   - Generated artifacts are stored under `outputs/<project>/<content_type>/<mode>/...`.
   - The directory layout separates reusable intermediate data from final presentation outputs.
   - This is useful for an architecture diagram because it shows persistence boundaries: source files and checkpoints on one side, generated deliverables on the other.

13. **Supporting code is mostly glue and utility**
   - `paper2slides/utils/` provides file/path/logging helpers.
   - `paper2slides/prompts/` centralizes LLM prompt templates.
   - These are shared support layers rather than independent subsystems, and they primarily feed the pipeline stages.

Overall, the repo is a **document-processing system with a resumable multi-stage Python pipeline**, exposed through both a **CLI** and an **interactive web UI**, and backed by **external LLM/image services** for content planning and visual generation.

Main entry points: [`paper2slides/core/pipeline.py`](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/pipeline.py) (Pipeline), [`api/server.py`](https://github.com/hkuds/paper2slides/blob/main/api/server.py) (API server), [`paper2slides/core/stages/plan_stage.py`](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/plan_stage.py) (Plan stage), [`paper2slides/core/stages/generate_stage.py`](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/generate_stage.py) (Generate stage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI"]
  node_cli_main["CLI entry<br/>python entrypoint<br/>[main.py]"]
  node_cli_module["Module entry<br/>python module<br/>[__main__.py]"]
end

subgraph group_grp_web["Web app"]
  node_api_server["API server<br/>python service<br/>[server.py]"]
  node_frontend_app["Frontend app<br/>react UI<br/>[App.jsx]"]
end

subgraph group_grp_core["Core pipeline"]
  node_pipeline["Pipeline<br/>orchestrator<br/>[pipeline.py]"]
  node_state[("State<br/>checkpoint store<br/>[state.py]")]
  node_rag_stage["RAG stage<br/>pipeline stage<br/>[rag_stage.py]"]
  node_summary_stage["Summary stage<br/>pipeline stage<br/>[summary_stage.py]"]
  node_plan_stage["Plan stage<br/>pipeline stage<br/>[plan_stage.py]"]
  node_generate_stage["Generate stage<br/>pipeline stage<br/>[generate_stage.py]"]
  node_raganything["RAGAnything<br/>document indexing<br/>[raganything.py]"]
  node_summary["Summary<br/>content extraction<br/>[paper.py]"]
  node_planner["Content planner<br/>presentation planning<br/>[content_planner.py]"]
  node_imagegen["Image generator<br/>asset generation<br/>[image_generator.py]"]
end

subgraph group_grp_support["Support"]
  node_prompts["Prompts<br/>prompt templates"]
  node_generator_config["Gen config<br/>runtime config<br/>[config.py]"]
  node_utils["Utilities<br/>shared helpers<br/>[file_utils.py]"]
end

node_external_ai(("AI providers<br/>external services"))

node_cli_main -->|"runs"| node_pipeline
node_cli_module -->|"dispatches"| node_cli_main
node_api_server -->|"triggers"| node_pipeline
node_frontend_app -->|"calls"| node_api_server
node_pipeline -->|"persists"| node_state
node_pipeline -->|"orchestrates"| node_rag_stage
node_pipeline -->|"orchestrates"| node_summary_stage
node_pipeline -->|"orchestrates"| node_plan_stage
node_pipeline -->|"orchestrates"| node_generate_stage
node_rag_stage -->|"indexes"| node_raganything
node_summary_stage -->|"extracts"| node_summary
node_plan_stage -->|"plans"| node_planner
node_plan_stage -->|"uses"| node_prompts
node_generate_stage -->|"renders"| node_imagegen
node_generate_stage -->|"depends on"| node_external_ai
node_imagegen -->|"reads"| node_generator_config
node_summary -->|"uses"| node_prompts
node_pipeline -->|"shares"| node_utils
node_api_server -->|"shares"| node_utils

click node_cli_main "https://github.com/hkuds/paper2slides/blob/main/paper2slides/main.py"
click node_cli_module "https://github.com/hkuds/paper2slides/blob/main/paper2slides/__main__.py"
click node_api_server "https://github.com/hkuds/paper2slides/blob/main/api/server.py"
click node_frontend_app "https://github.com/hkuds/paper2slides/blob/main/frontend/src/App.jsx"
click node_pipeline "https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/pipeline.py"
click node_state "https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/state.py"
click node_rag_stage "https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/rag_stage.py"
click node_summary_stage "https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/summary_stage.py"
click node_plan_stage "https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/plan_stage.py"
click node_generate_stage "https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/generate_stage.py"
click node_raganything "https://github.com/hkuds/paper2slides/blob/main/paper2slides/raganything/raganything.py"
click node_summary "https://github.com/hkuds/paper2slides/blob/main/paper2slides/summary/paper.py"
click node_planner "https://github.com/hkuds/paper2slides/blob/main/paper2slides/generator/content_planner.py"
click node_imagegen "https://github.com/hkuds/paper2slides/blob/main/paper2slides/generator/image_generator.py"
click node_prompts "https://github.com/hkuds/paper2slides/blob/main/paper2slides/prompts/content_planning.py"
click node_generator_config "https://github.com/hkuds/paper2slides/blob/main/paper2slides/generator/config.py"
click node_utils "https://github.com/hkuds/paper2slides/blob/main/paper2slides/utils/file_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_main,node_cli_module toneBlue
class node_api_server,node_frontend_app toneAmber
class node_pipeline,node_state,node_rag_stage,node_summary_stage,node_plan_stage,node_generate_stage,node_raganything,node_summary,node_planner,node_imagegen toneMint
class node_prompts,node_generator_config,node_utils toneRose
class node_external_ai toneNeutral
```

## Components

### CLI

Command-line entry path

- [CLI entry](https://github.com/hkuds/paper2slides/blob/main/paper2slides/main.py): python entrypoint · Command-line launcher for the shared pipeline · `paper2slides/main.py`
- [Module entry](https://github.com/hkuds/paper2slides/blob/main/paper2slides/__main__.py): python module · Supports python -m invocation · `paper2slides/__main__.py`

### Web app

API backend and React frontend

- [API server](https://github.com/hkuds/paper2slides/blob/main/api/server.py): python service · Backend service exposing pipeline operations · `api/server.py`
- [Frontend app](https://github.com/hkuds/paper2slides/blob/main/frontend/src/App.jsx): react UI · Interactive web interface for upload, config, status, and preview · `frontend/src/App.jsx`

### Core pipeline

Shared document-to-slides engine

- [Pipeline](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/pipeline.py): orchestrator · Coordinates the document-to-slides workflow · `paper2slides/core/pipeline.py`
- [State](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/state.py): checkpoint store · Persists resume and stage checkpoint state · `paper2slides/core/state.py`
- [RAG stage](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/rag_stage.py): pipeline stage · Indexing and retrieval preparation stage · `paper2slides/core/stages/rag_stage.py`
- [Summary stage](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/summary_stage.py): pipeline stage · Extracts structure and normalizes paper content · `paper2slides/core/stages/summary_stage.py`
- [Plan stage](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/plan_stage.py): pipeline stage · Builds the presentation blueprint · `paper2slides/core/stages/plan_stage.py`
- [Generate stage](https://github.com/hkuds/paper2slides/blob/main/paper2slides/core/stages/generate_stage.py): pipeline stage · Produces final slide or poster assets · `paper2slides/core/stages/generate_stage.py`
- [RAGAnything](https://github.com/hkuds/paper2slides/blob/main/paper2slides/raganything/raganything.py): document indexing · Parses and indexes source documents for retrieval · `paper2slides/raganything/raganything.py`
- [Summary](https://github.com/hkuds/paper2slides/blob/main/paper2slides/summary/paper.py): content extraction · Extracts paper structure, figures, tables, and cleaned content · `paper2slides/summary/paper.py`
- [Content planner](https://github.com/hkuds/paper2slides/blob/main/paper2slides/generator/content_planner.py): presentation planning · Converts extracted content into slide and poster structure · `paper2slides/generator/content_planner.py`
- [Image generator](https://github.com/hkuds/paper2slides/blob/main/paper2slides/generator/image_generator.py): asset generation · Builds the final presentation images · `paper2slides/generator/image_generator.py`

### Support

Shared prompts, config, and utilities

- [Prompts](https://github.com/hkuds/paper2slides/blob/main/paper2slides/prompts/content_planning.py): prompt templates · Shared LLM prompt templates for extraction, planning, and generation · `paper2slides/prompts/content_planning.py`
- [Gen config](https://github.com/hkuds/paper2slides/blob/main/paper2slides/generator/config.py): runtime config · Provider, model, and base URL settings for generation · `paper2slides/generator/config.py`
- [Utilities](https://github.com/hkuds/paper2slides/blob/main/paper2slides/utils/file_utils.py): shared helpers · File, path, and logging helpers used across the codebase · `paper2slides/utils/file_utils.py`

### Other components

- **AI providers**: external services · LLM and image APIs such as OpenRouter and Gemini

## Connections

- CLI entry → Pipeline: runs · CLI invokes the shared pipeline
- Module entry → CLI entry: dispatches · Module entry routes to the CLI launcher
- API server → Pipeline: triggers · Backend starts and controls pipeline jobs
- Frontend app → API server: calls · UI communicates with the backend service
- Pipeline → State: persists · Pipeline writes checkpoints and resume state
- Pipeline → RAG stage: orchestrates · First stage in the document flow
- Pipeline → Summary stage: orchestrates · Second stage in the document flow
- Pipeline → Plan stage: orchestrates · Third stage in the document flow
- Pipeline → Generate stage: orchestrates · Final stage in the document flow
- RAG stage → RAGAnything: indexes · Stage delegates document parsing and retrieval setup
- Summary stage → Summary: extracts · Stage delegates content extraction and normalization
- Plan stage → Content planner: plans · Stage builds the slide or poster blueprint
- Plan stage → Prompts: uses · Planning behavior is shaped by prompt templates
- Generate stage → Image generator: renders · Stage produces final visual assets
- Generate stage → AI providers: depends on · Image generation is provider-driven
- Image generator → Gen config: reads · Generation settings determine provider and model selection
- Summary → Prompts: uses · Extraction can leverage shared prompt templates
- Pipeline → Utilities: shares · Common helpers support filesystem and logging concerns
- API server → Utilities: shares · Backend uses shared helpers for service operations