The problem: you solve a sliding-window problem, learn a SQL window function, fix a Docker volume bug — and three weeks later it's gone. CodeShelf turns everything you learn into an AI-generated, spaced-repetition recall system that comes back to you — on screen, in your headphones, offline, and in your inbox.
Live at code-shelf-eight.vercel.app — sign up in seconds. First request may take ~30s while the free-tier API wakes up.
Screens captured from a local instance seeded with demo data.
| Layer | Stack |
|---|---|
| Frontend | React 19, Vite 8, React Router 7, CodeMirror 6, Lucide, custom canvas nebula + cursor design system — deployed on Vercel |
| Backend | FastAPI (async), SQLAlchemy 2 async, Alembic (10 migrations), Pydantic settings — deployed on Render |
| Data | Neon serverless PostgreSQL (SQLite for local dev) — 15 tables |
| AI | Gemini (typed card generation, recall chat, email intros), Hugging Face Space summaries, offline fallbacks |
| Clients | Web app · Chrome MV3 extension · VS Code extension · Expo mobile app |
| Ops | GitHub Actions cron (daily / weekly / streak / cleanup), health checks, cold-start-aware retries |
Spaced-repetition scheduler
| Rating | Next interval | Memory strength |
|---|---|---|
| Forgot / Again | 1 day | −0.25 |
| Hard | +1 day (min 2) | +0.05 |
| Good | +4 days (min 4) | +0.18 |
| Easy | ×2 (min 7) | +0.30 |
Weak topics are mined from forgot/hard review logs and fed back into the dashboard, the revision queue and the daily email.
Security
- JWT auth with bcrypt password hashing and strict email/password validation.
- Email verification and every email action link are signed, expiring, purpose-scoped JWTs bound to the account email.
- GitHub OAuth tokens are Fernet-encrypted at rest through a SQLAlchemy
TypeDecorator, with a data migration for existing rows. - Extension pairing uses single-use, SHA-256-hashed codes consumed atomically (
DELETE … RETURNING) — the long-lived token never crossespostMessage. - Cron endpoints require a shared secret (constant-time compare) and refuse to run in production without one; production refuses to boot with the default JWT secret.
AI pipeline that never breaks the UX
- Gemini is prompted for strict JSON (six typed cards); responses are de-fenced, boundary-extracted, trailing-comma-repaired and validated card by card.
- Hugging Face summaries run with a 10s budget and fall back to an extractive summary.
- Every AI feature has a deterministic fallback, so the app works with zero API keys.
Free-tier engineering
- Render's free tier blocks outbound SMTP, so mail goes through a pluggable
mailer— a Google Apps Script Gmail relay over HTTPS (shared-secret guarded), Brevo, or Resend. - Scheduled jobs run on GitHub Actions instead of paid cron: a reusable workflow wakes the sleeping instance, retries transient failures, and fails loudly only on real misconfiguration.
- Email sends are slot-based per user timezone with duplicate protection, so a cron firing every 30 min never double-sends.
Prerequisites: Node ≥ 18, Python ≥ 3.11. Works out of the box with SQLite — add a .env in the repo root only to configure the variables below.
git clone https://github.com/Yuvika687/CodeShelf.git && cd CodeShelf
npm install
pip install -r backend-py/requirements.txt
npm run migrate # Alembic → SQLite (or Neon if DATABASE_URL is set)
npm run dev:api # FastAPI → http://127.0.0.1:8000/api (health: /api/health)
npm run dev # React → http://127.0.0.1:5173Environment variables
| Variable | Purpose |
|---|---|
DATABASE_URL |
postgresql+asyncpg://…neon.tech/db?sslmode=require (defaults to SQLite) |
JWT_SECRET |
Token signing — required in production |
FRONTEND_URL / BACKEND_URL |
Public URLs used in redirects and email links |
ENVIRONMENT |
production enables strict checks |
CRON_SECRET |
Shared secret for /api/email/cron-* (also a GitHub Actions secret) |
GMAIL_SCRIPT_URL / GMAIL_SCRIPT_SECRET |
Gmail relay (tools/gmail-relay) |
BREVO_API_KEY + MAIL_FROM_EMAIL · RESEND_API_KEY |
Alternative email providers |
GEMINI_API_KEY · HF_API_KEY · HF_SPACE_ID |
AI features (optional) |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET |
GitHub sync (optional) |
TOKEN_ENCRYPTION_KEY |
Key for stored GitHub tokens (defaults to one derived from JWT_SECRET) |
Project structure
CodeShelf/
├── src/ React app — pages, layout, nebula/cursor components, API client
├── backend-py/
│ ├── app/
│ │ ├── routes/ auth · notes · problems · mistakes · revision · concepts
│ │ │ email · github · extension · dashboard · activity · ai
│ │ ├── models/ SQLAlchemy models (15 tables)
│ │ ├── mailer.py Gmail relay / Brevo / Resend delivery
│ │ ├── crypto.py at-rest encryption for third-party tokens
│ │ ├── ai_service.py Gemini card generation + JSON repair
│ │ └── github_utils.py OAuth, repo listing, solution commits
│ ├── alembic/ 10 migrations
│ └── render.yaml Render blueprint
├── extensions/ Chrome (MV3) + VS Code extensions
├── mobile/ Expo / React Native app
├── tools/gmail-relay/ Google Apps Script mail relay
└── .github/workflows/ scheduled email jobs
Extensions & mobile
- Chrome — load
extensions/chromeunpacked (or the zip inpublic/downloads), click Connect CodeShelf, then Capture current page on any LeetCode problem. See EXTENSIONS.md. - VS Code — open
extensions/vscode, press F5, runCodeShelf: Connect/Save Current File/Commit Current File to GitHub. - Mobile —
cd mobile && npm install && npm start, scan the QR code with Expo Go.
| Piece | Where | Notes |
|---|---|---|
| Frontend | Vercel | VITE_API_BASE_URL=https://<api>.onrender.com/api |
| API | Render (backend-py/render.yaml) |
build runs alembic upgrade head |
| Database | Neon | serverless Postgres |
| Scheduled email | GitHub Actions | add repo secret CRON_SECRET (same value as the API) |
Built by Yuvika Malhotra · LinkedIn · Email
© 2026 Yuvika Malhotra. All rights reserved.







