Everything an NUS student needs to revise for finals, on one screen.
Log in with a Canvas token. CramBot finds your courses and gathers every slide, announcement, deadline and past paper in one place. All course material is full-text searchable down to the page, and CramBot plans what to revise each day before the exams arrive.
Live: nuscan.duckdns.org (demo data; uploading past papers is live)
English · 简体中文
Screenshots use the bundled mock Canvas (
scripts/dev.sh --mock), so they contain no real course data. The UI language is Chinese.
| Feature | What it does |
|---|---|
| All-in-one dashboard | Exam countdown, a week calendar with Canvas deadlines, and every course with its revision progress. All of it fits on one screen. |
| Todo cards | Today / This week / Memo cards. Canvas deadlines appear as an automatic card and can be added to your todos with one click. "Suggest" splits the day across courses by days-to-exam. |
| Pomodoro + heatmap | A timer bound to a course or a todo. It keeps accurate time in background tabs. Twelve weeks of study history are shown as a heatmap. |
| In-browser reader | PDF reader with continuous scroll and selectable text. You can jump to any page, and files reopen where you stopped. |
| Full-text search per course | Searches every PDF, PPTX, DOCX and code file in a course, with ranked, highlighted results. Each result links to the exact page. |
| Review map | Lectures in order, each with its definitions and theorems (or slide topics). Also: exercises paired with their solutions, the exam date from NUSMods, and a "revise today" suggestion. |
| Past papers | Uploaded by students and reviewed before publishing. Sorted by type (homework, quiz, midterm, final) and by calendar year, with solutions paired to their papers. Visible only to students enrolled in the course. |
| Contributors | Everyone whose upload is approved is credited on the site and in CONTRIBUTORS.md. Uploading needs no account. |
| Light & dark themes | "Paper" for daytime and "Night reading" for late sessions. |
![]() Review map: exam countdown, progress, and the definitions and theorems in each lecture |
![]() Search: every course file, ranked, linking straight to the page |
![]() Night reading theme |
![]() Single-column mobile layout |
Requirements: Python 3.11+ and Node 22+. You don't need an NUS account.
git clone https://github.com/tired-wind/crambot.git && cd crambot
scripts/dev.sh --mockOpen http://localhost:5173 and log in with demo-token. The first run creates .venv/ and installs dependencies. Interactive API docs: http://localhost:8000/api/docs.
To use real NUS Canvas, run scripts/dev.sh and log in with your own token. You create one in Canvas → Account → Settings → New Access Token. The token stays in your browser tab.
flowchart LR
B["React SPA<br/>(token in sessionStorage)"] -- "Bearer token" --> A["FastAPI"]
A -- "per request" --> C["Canvas API"]
A -- "no token, signed URL" --> S["Canvas file storage"]
A --> N["NUSMods<br/>exam dates"]
A --> F[("SQLite FTS5<br/>course index")]
A --> P["parser process pool<br/>PDFium · pptx · docx"]
P --> F
There is no user database. Canvas is the source of truth and is queried live with the student's own token. The server keeps only course-level data: the text index and past papers. Personal study data (todos, pomodoros, reading position) stays in the browser.
Technical highlights:
- The token is never stored on the server. It is sent only in a request header and cached for 5 minutes, keyed by its SHA-256 hash, never the token itself. Every course route checks that the user is enrolled; for courses they aren't in, it returns 404 rather than 403, so it doesn't reveal that the course exists.
- Fast search on real data. 103 files (3,202 pages) from 5 real courses were indexed in 42 s, and median search latency is 3 ms. Search uses SQLite FTS5 with BM25 ranking, and queries are sanitised to prevent FTS syntax injection.
- Crash-isolated parsing. PDFium is not thread-safe, so documents are parsed in a separate process pool. If a malformed file crashes a worker, the pool is rebuilt and the API keeps serving.
- Deterministic review map. Lecture order, theorem extraction and exercise–solution pairing are rule-based, not LLM-based. The output is reproducible, testable and free to run.
crambot/
├── backend/
│ ├── crambot/ # FastAPI app: Canvas client, file streaming, text extraction,
│ │ # full-text index, review map, NUSMods exam dates, past papers
│ └── tests/
├── frontend/
│ └── src/
│ ├── pages/ # dashboard, course page, review map, search, reader, login
│ ├── pomodoro/ # timer state and widgets
│ └── lib/ # pure, unit-tested logic: daily plan, todos, heatmap, storage
├── scripts/
│ ├── dev.sh # one-command dev environment (--mock for a fake Canvas)
│ ├── mock_canvas.py # mock Canvas API with generated PDFs
│ ├── make_demo_papers.py # demo past papers
│ ├── start.sh # container entrypoint (demo mode starts the mock Canvas)
│ ├── sync_contributors.py # regenerate CONTRIBUTORS.md from the live site
│ └── canvas_probe.py # check what a Canvas token can access
├── deploy/ # Docker Compose + Caddy for a server
└── docs/images/ # screenshots
.venv/bin/python -m unittest discover -s backend/tests
.venv/bin/python -m unittest discover -s scripts/tests
npm --prefix frontend run lint
npm --prefix frontend test
npm --prefix frontend run build # type check + bundleCI runs all of the above on every push (Python 3.11 / 3.13, Node 22 / 24).
| Variable | Default | |
|---|---|---|
CANVAS_BASE_URL |
https://canvas.nus.edu.sg |
Canvas instance |
PAST_PAPERS_DIR |
data/past_papers |
Put papers in <dir>/<COURSE_CODE>/*.pdf |
INDEX_DB |
data/index.sqlite |
Full-text index |
FRONTEND_DIST |
frontend/dist |
Built frontend, served by FastAPI |
PROFILE_CACHE_TTL |
300 |
Seconds to cache a user's course list |
DEMO_MODE |
off | Public demo: bundled mock Canvas, demo account only, real tokens rejected |
ADMIN_PASSWORD |
unset | Enables the review page at /admin; leave unset to disable it |
UPLOADS_DIR / SUBMISSIONS_DB |
data/uploads, data/submissions.sqlite |
Pending uploads and the review log |
PAPER_LIBRARY_DIR |
data/past_papers |
Where approved papers are filed |
Production runs as a single process. Build the frontend, then start the server:
npm --prefix frontend run build
.venv/bin/uvicorn crambot.app:create_app --factory --app-dir backend --host 0.0.0.0 --port 8000Serve it over HTTPS only. See SECURITY.md.
With Docker:
docker build -t crambot .
docker run -p 8000:8000 -e DEMO_MODE=1 crambot # public demo with mock dataOn a small server without Docker, deploy/native/ installs the site as a systemd service behind an existing Caddy and adds daily backups; deploy/native/deploy.sh builds and ships a release. With Docker, deploy/ runs the site behind Caddy, which obtains HTTPS certificates automatically. Uploads are kept on a persistent volume. Copy deploy/.env.example to deploy/.env, set the domain and admin password, then run docker compose -f deploy/docker-compose.yml up -d --build.
Approved papers are filed as <AY>_<Sem>_<Type>[_Solutions].pdf (e.g. 2023-24_Sem1_Final.pdf, 2023-24_Sem1_Final_Solutions.pdf). Type and calendar year are read from the name: Sem 1 counts as the first calendar year of the academic year, while Sem 2 and Special Term count as the second.
- Canvas integration, dashboard, course pages, past papers
- In-browser reader, per-course full-text search, review map
- Pomodoro, daily plan, heatmap, todo cards, light/dark themes
- Past papers sorted by type and year; student uploads with review and contributor credits
- Sign in with Canvas (OAuth2), pending approval from NUS IT
- Knowledge-point roadmap for each course
- Q&A over course material with page-level citations, running on free local open-source models
- Past-paper topic frequency analysis
Version history: CHANGELOG.md · Releases
Code is released under the MIT License.
- The decorative engravings are public domain or CC0: Trouvelot's The November Meteors (1881–82), and Benjamin Waterhouse Hawkins's Megalosaurus and Iguanodon (1854). Sources are in CREDITS.md.
- The login illustration is used with permission and is not covered by the MIT license.
Exam dates come from NUSMods.




