How hkuds/paper2slides works
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: pipeline.py Pipeline · server.py API server · plan_stage.py Plan stage · generate_stage.py Generate stage
Components 18
CLI
Command-line entry path
- CLI entry · Command-line launcher for the shared pipeline
paper2slides/main.py - Module entry · Supports python -m invocation
paper2slides/__main__.py
Web app
API backend and React frontend
- API server · Backend service exposing pipeline operations
api/server.py - Frontend app · Interactive web interface for upload, config, status, and preview
frontend/src/App.jsx
Core pipeline
Shared document-to-slides engine
- Pipeline · Coordinates the document-to-slides workflow
paper2slides/core/pipeline.py - State · Persists resume and stage checkpoint state
paper2slides/core/state.py - RAG stage · Indexing and retrieval preparation stage
paper2slides/core/stages/rag_stage.py - Summary stage · Extracts structure and normalizes paper content
paper2slides/core/stages/summary_stage.py - Plan stage · Builds the presentation blueprint
paper2slides/core/stages/plan_stage.py - Generate stage · Produces final slide or poster assets
paper2slides/core/stages/generate_stage.py - RAGAnything · Parses and indexes source documents for retrieval
paper2slides/raganything/raganything.py - Summary · Extracts paper structure, figures, tables, and cleaned content
paper2slides/summary/paper.py - Content planner · Converts extracted content into slide and poster structure
paper2slides/generator/content_planner.py - Image generator · Builds the final presentation images
paper2slides/generator/image_generator.py
Support
Shared prompts, config, and utilities
- Prompts · Shared LLM prompt templates for extraction, planning, and generation
paper2slides/prompts/content_planning.py - Gen config · Provider, model, and base URL settings for generation
paper2slides/generator/config.py - Utilities · File, path, and logging helpers used across the codebase
paper2slides/utils/file_utils.py
Other components
- AI providers · LLM and image APIs such as OpenRouter and Gemini
Connections 19
- 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