Inspiration
Parents and teachers often receive worksheets as scanned PDFs, phone photos, or screenshots with handwritten answers already marked on them. Preparing a clean practice version for students is surprisingly tedious: remove answers, preserve diagrams, retype questions, and then create a separate answer key with explanations.
pdf-exercise-web was inspired by this everyday workflow: turning messy worksheet images into printable, student-ready materials with minimal manual editing.
What it does
pdf-exercise-web lets users upload a worksheet image or PDF and generates downloadable learning materials:
- A clean student worksheet PDF with answers removed
- A complete answer-and-explanation PDF
- Structured transcription data and Markdown drafts
- Support for math, physics, English, and other subjects
- Diagram handling strategies, including source-image crops for complex geometry or circuit diagrams
- Optional image preprocessing with OpenCV for photographed or skewed worksheets
- Token usage reporting
- English / Chinese interface switching
- Admin tools for visitor stats and trial access tokens
Users can provide their own OpenAI-compatible API key in the browser, or use a site-provided trial/shared access link.
How we built it
We built the app as a lightweight single-server web application designed for a small VPS.
The stack:
- FastAPI for the backend
- Jinja2 templates plus vanilla JavaScript for the frontend
- SQLite for jobs, visitor logs, trial tokens, and queue state
- Local filesystem storage for uploads and generated artifacts
- A single background worker process for queued worksheet jobs
- OpenCV and Pillow for image preprocessing
- XeLaTeX / ReportLab for PDF generation
- Nginx + systemd for VPS deployment
- Cloudflare in front of the public domain
We also added a small custom i18n layer using JSON locale files, with English as the default and Chinese available via a language switcher.
Challenges we ran into
The hardest part was preserving worksheet fidelity.
Some worksheets contain irregular geometry diagrams, function graphs, circuit diagrams, or real object illustrations. Recreating these with LaTeX/TikZ can introduce subtle mistakes, so we designed a diagram strategy system: simple regular diagrams can be redrawn, while complex or uncertain diagrams are preserved with padded source-image crops.
Another challenge was working within a small VPS environment. We avoided Docker, Redis, PostgreSQL, and heavy frontend frameworks, choosing a queue built on SQLite and a single worker to keep memory usage predictable.
Security and privacy were also important. API keys are not stored in the database; they are only written temporarily for a job and deleted after the worker reads them. Trial tokens are stored as hashes, not plaintext.
Accomplishments that we're proud of
We are proud that pdf-exercise-web is not just a demo page, but a real deployed workflow:
- Users can upload actual worksheet photos or PDFs
- The service queues jobs safely on a small VPS
- Generated files are downloadable and automatically cleaned up
- Trial tokens can be created, limited, revoked, or bound on first use
- Visitor statistics help the maintainer understand usage without storing worksheet content
- The interface now supports English and Chinese
- The project is open source and documented for self-hosting
We are especially proud of making the system practical for real parents and teachers, not just technically interesting.
What we learned
We learned that educational document processing is less about “OCR everything” and more about preserving intent and layout.
For math and physics worksheets, diagrams are often part of the question. If a graph, angle, or circuit is slightly wrong, the generated worksheet becomes misleading. This pushed us toward a hybrid approach: combine AI understanding, image preprocessing, original diagram crops, and PDF generation instead of relying on one technique.
We also learned that small-server architecture can go surprisingly far when the system is designed carefully: SQLite, local files, and one worker are enough for an MVP if limits and cleanup are clear.
What's next for pdf-exercise-web
Next, we want to improve:
- Better worksheet transcription quality and review tools
- More robust image deskewing and page detection
- A visual editor for correcting extracted questions before PDF generation
- More subject-specific answer explanation templates
- More languages beyond English and Chinese
- Better admin controls for trial users and quotas
- Batch worksheet processing
- Cleaner self-hosting setup and deployment documentation
Longer term, pdf-exercise-web could become a practical open-source tool for parents, teachers, tutors, and small learning communities who need fast, printable practice materials from imperfect scans and photos.
Log in or sign up for Devpost to join the conversation.