The Flashcard Engine

link: https://flashcard-engine-0y75.onrender.com

An AI-assisted flashcard platform that converts PDFs into practice-ready decks and schedules reviews using spaced repetition.

What This Solves

Students usually re-read notes passively. This app pushes active recall and long-term retention:

• Upload a PDF and instantly generate high-quality flashcards.
• Practice cards with a review loop that adapts to your performance.
• Track mastery, weak spots, and upcoming reviews.
• Manage multiple decks with search and quick resume.

Core Features

• PDF ingestion and text extraction using pdf-parse.
• AI card generation using OpenRouter chat completions (OPENROUTER_API_KEY).
• Heuristic fallback generator when no API key is present.
• SM-2 inspired spaced repetition (Again/Hard/Good/Easy).
• Deck browser with due count and mastery score.
• Study queue that prioritizes due cards.
• Progress panel with weak/improving/strong buckets.
• Responsive UI built with React + Vite.

Tech Stack

• Frontend: React, TypeScript, Vite
• Backend: Node.js, Express, TypeScript
• Storage: JSON file store (server/data/decks.json)
• PDF Parsing: pdf-parse
• Validation: zod

Local Setup

1. Install dependencies:

npm install
npm install --prefix server
npm install --prefix client

2. Create env file from sample:

cp .env.example .env

3. Optional but recommended: set OPENROUTER_API_KEY in .env.

4. Run both frontend and backend:

npm run dev

5. Open:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8787/api/health

How Spaced Repetition Works

Each card stores:

• repetitions
• intervalDays
• easeFactor
• dueAt
• reviewCount
• lapses

Rating behavior:

• Again: resets repetitions, lowers ease factor, reintroduces quickly.
• Hard/Good/Easy: increases intervals and adjusts ease factor.

Cards due now are surfaced first in each study queue.

API Overview

• GET /api/decks?q=...
• POST /api/decks/import-pdf (multipart field: file)
• GET /api/decks/:deckId
• GET /api/decks/:deckId/study?limit=20
• POST /api/decks/:deckId/review body: { cardId, rating }
• GET /api/decks/:deckId/progress

Deployment (Render)

This repo includes render.yaml for one-service deployment.

Option A: Blueprint deploy

1. Push this repo to GitHub.
2. In Render, choose New > Blueprint.
3. Select the repository.
4. Add OPENROUTER_API_KEY in Render environment variables.
5. Deploy.

Option B: Manual web service

• Build command: npm install && npm run build
• Start command: npm run start
• Environment variables:
  • OPENROUTER_API_KEY (required for AI generation)
  • OPENROUTER_MODEL (optional, defaults to openai/gpt-4.1-mini)
  • OPENROUTER_SITE_URL (optional but recommended for OpenRouter analytics)
  • OPENROUTER_APP_NAME (optional display name for requests)
  • PORT (Render sets this automatically)

Future Improvements

• Per-user auth and cloud DB instead of file storage.
• Better extraction for equation-heavy PDFs and scanned docs (OCR).
• Deck editing (merge/split/regenerate cards).
• Richer analytics (retention over time, goal streaks).
• Offline mobile mode with sync.