Trivia

Trivia is a local-first Electron desktop app for testing and building general knowledge with multiple-choice quiz stacks, adaptive retries, a dark interface, and editable JSON content.

You don't just get shown answers — you pick an answer, learn from mistakes, and get retested on what you miss. Questions you keep getting right fade out of rotation; questions you fail come back until they stick.

Project status

Working app. npm install then npm run dev opens the Electron window. Ships with a large offline library (~132,000 questions across 132 stacks) and scripts to generate or download more.

Core ideas

• Quiz-first: every card is multiple choice. Learn by trial and error.
• Adaptive: a lightweight spaced-repetition model prioritizes weak/new questions and hides mastered ones.
• Local-first: all cards and progress live in JSON files on disk.
• Easy to edit: stacks are normal .json files under library/stacks/.
• Easy to expand: drop JSON files into the stack folder and click Reload.
• Dark, calm UI: comfortable for long study sessions.

What it does

Study (Quiz)

• Browse a library of trivia stacks.
• Answer multiple-choice questions (mouse or keys 1–4).
• Wrong answers reveal the correct one and are re-queued later in the session.
• Correct answers clear the question from the session.
• Session summary shows your score at the end.

Adaptive scheduling

Progress is saved to library/progress/progress.json after every answer.

• Wrong → due again in ~2 minutes (keeps cycling), ease lowered, streak reset.
• Right → interval grows with the streak (1 → 3 → 7 → 14+ days), ease raised.
• Mastered (streak ≥ 3 and interval ≥ 7 days) → skipped until due again.

Each study session builds a prioritized queue: due, new, and weak questions first; mastered/not-due questions are held back.

Manage stacks

Stacks live in library/stacks/*.json. The app:

• Loads all valid stack JSON files (ignores files starting with _).
• Skips broken JSON without crashing.
• Shows title, description, source, and card count.
• Provides Open JSON folder and Reload stacks buttons.

Settings

A Settings page (sidebar) holds debugging options:

• Open DevTools on launch — off by default.
• Open DevTools now — opens Chromium DevTools on demand.

Settings persist in settings.json under the app's userData folder.

Quick start

cd F:/sites/FlashCards
npm install
npm run dev

The library already contains stacks, so the app is playable immediately. npm run dev uses Electron + Vite; renderer UI changes hot-reload, main/preload changes need an Electron restart.

Content library

The bundled library is generated/collected by several scripts:

Command	What it does
npm run seed-stacks	Write built-in hand-written stacks from scripts/trivia-bank.mjs
npm run generate-facts	Generate fact-based stacks (capitals, elements, presidents, etc.)
npm run fetch-trivia-api	Download/merge questions from The Trivia API
npm run fetch-stacks	Download from Open Trivia DB (slow; rate-limited)
npm run pad-stacks	Raise thin stacks up to a target size (default 501; set PAD_TARGET)

PAD_TARGET example (raise everything to 1000+):

# PowerShell
$env:PAD_TARGET='1001'; node scripts/pad-stacks-to-300.mjs

Sources retain their source and license metadata:

• Built-in / generated cards: CC0 1.0 (public domain)
• Open Trivia DB: https://opentdb.com/ — CC BY-SA 4.0
• The Trivia API: https://the-trivia-api.com/

Project layout

F:/sites/FlashCards
├─ package.json
├─ electron.vite.config.ts
├─ tsconfig.json
├─ scripts/
│  ├─ seed-stacks.mjs             built-in stacks
│  ├─ trivia-bank.mjs             built-in question bank
│  ├─ generate-fact-stacks.mjs    fact stacks (batch 1)
│  ├─ generate-fact-stacks-extra.mjs  fact stacks (batch 2)
│  ├─ fetch-trivia-api.mjs        The Trivia API downloader
│  ├─ fetch-stacks.mjs            Open Trivia DB downloader
│  └─ pad-stacks-to-300.mjs       raise thin stacks to a target size
├─ src/
│  ├─ main/          Electron main process, library + settings services
│  ├─ preload/       typed bridge exposed as window.flashcards
│  └─ renderer/      React app (Home, Library, Study, Progress, Settings)
├─ library/
│  ├─ stacks/        editable quiz stack JSON files
│  └─ progress/      progress JSON
└─ specs/            product and implementation specs

Stack JSON format

Each stack is one file under library/stacks/.

{
  "schemaVersion": "1.0.0",
  "id": "stack_geography",
  "title": "Geography",
  "description": "World capitals, maps, landmarks, rivers, mountains, and flags.",
  "source": "Trivia built-in (generated facts)",
  "license": "CC0 1.0",
  "tags": ["trivia", "geography"],
  "updatedAt": "2026-07-18T00:00:00.000Z",
  "cards": [
    {
      "id": "card_unique_id",
      "front": "What is the capital of Japan?",
      "back": "Tokyo",
      "choices": ["Kyoto", "Osaka", "Tokyo", "Sapporo"],
      "explanation": "Optional extra context shown after answering.",
      "difficulty": "easy",
      "tags": ["capitals", "asia"]
    }
  ]
}

choices should include the correct back value. If a card has no choices, the app fills distractors from other answers in the same stack so quiz mode still works.

Progress JSON format

Progress is stored separately so stacks stay reusable.

{
  "schemaVersion": "1.0.0",
  "cards": {
    "card_unique_id": {
      "stackId": "stack_geography",
      "seen": 3,
      "correct": 2,
      "streak": 2,
      "ease": 2.66,
      "intervalDays": 3,
      "dueAt": "2026-07-22T10:00:00.000Z",
      "lastResult": "good",
      "updatedAt": "2026-07-18T10:00:00.000Z"
    }
  },
  "sessions": []
}

Development scripts

Command	Purpose
npm run dev	Start Electron + Vite dev server
npm run typecheck	TypeScript check
npm run build	Production build
npm run dist	Windows installer via electron-builder
npm run seed-stacks	Regenerate built-in stacks
npm run generate-facts	Regenerate fact stacks
npm run fetch-trivia-api	Download/merge from The Trivia API
npm run fetch-stacks	Download from Open Trivia DB
npm run pad-stacks	Raise thin stacks to a target size

Architecture

• Electron main process handles all filesystem access.
• A typed preload API is exposed as window.flashcards.
• The renderer is React only and never touches Node fs directly.
• Routes: #/ Home, #/library Library, #/study/:stackId Study, #/stats Progress, #/settings Settings.

Important implementation rules

• Do not store canonical card/progress data in a hidden database.
• Do not require a restart for normal renderer/UI edits during development.
• Do not make the renderer access Node filesystem directly.
• Keep all stack/progress files human-readable, pretty-printed JSON.
• Preserve source and license metadata on downloaded stacks.

Specs

• specs/README.md
• specs/product.md
• specs/data-model.md
• specs/architecture.md
• specs/content-sources.md
• specs/roadmap.md

Attribution

Downloaded trivia content retains attribution and license metadata.

• Open Trivia DB: https://opentdb.com/ — CC BY-SA 4.0
• The Trivia API: https://the-trivia-api.com/
• Built-in / generated content: CC0 1.0