How rkstgr/papermake works
Project Type and Purpose
• Papermake is a full-stack PDF generation service.
• It consists of:
• A Web UI (Next.js/React) for users to manage templates and request renders
• An HTTP API server (Rust) exposing template and render endpoints
• Background worker(s) to process heavy PDF generation jobs
• A core library (Rust) that drives Typst to compile templates into PDFs
• Storage layers (database for metadata, S3-compatible object store for PDFs)
File Structure and Architecture
Top-level crates/ directories:
• papermake/ Core library (template building, caching, rendering)
• papermake-registry/ Template versioning & storage abstraction (File, SQLite, Postgres, S3, TiKV)
• papermake-server/ HTTP API server + background worker harness
• papermake-worker/ Standalone worker binary (for horizontal scaling)
• webui/ Next.js front-end (React + TypeScript + Tailwind)
• docker-compose.yml Definitions for MinIO (S3) and other services
Main Components
A. WebUI
• Next.js frontend (Pages, API client)
• Communicates via HTTP(S) to the API server
B. API Server
• Routes (templates, renders, batch renders, analytics, websockets)
• Services layer orchestrating registry & render logic
• Configuration (DB URL, S3 endpoint, Worker settings)
C. Template Registry
• CRUD operations on templates and versions
• Storage backends (SQLite/Postgres, filesystem, S3, etc.)
D. Background Worker(s)
• Pull jobs from a queue or invoked by server’s worker.rs
• Uses papermake core library + Typst to generate PDF
• Stores PDF in S3 and updates job status in DB
E. Core Library (papermake)
• TemplateBuilder, Schema validation, caching, render API
• Embedded Typst engine
F. Storage & Infrastructure
• Relational DB (SQLite, Postgres) for metadata & job states
• S3-compatible object store (MinIO) for storing rendered PDFs
• Docker Compose orchestrates these in local/dev
Relationships & Data Flows
1. User (Browser) → WebUI
• Template creation / listing / render requests
2. WebUI → API Server (HTTP)
• POST /api/templates → Template Registry
• POST /api/renders → Enqueue render job
3. API Server → Database
• Persist template metadata, versions, job records
4. API Server → Worker(s)
• Enqueue jobs (could be in-process or external message queue)
5. Worker → Core Library
• Load template & data → Render via Typst → Generate PDF bytes
6. Worker → S3 Storage
• Upload PDF file → Get object URL/path
7. Worker → Database
• Update job status (queued → in-progress → completed)
8. API Server → WebUI
• Expose job status & PDF download URLs via HTTP or WebSocket
Important Architectural Patterns
• Modular Rust crates (core / registry / server / worker)
• Separation of concerns: HTTP API vs. background processing
• Pluggable storage backends via traits (registry crate)
• Caching layer in core library for high-throughput rendering
• Optional horizontal scaling of worker binary