← Back to portfolio

Flashcards – study app

A personal study tool I'm building to revise for the exams in my standalone courses — and at the same time to go deeper into modern, spec-driven development with Claude Code and OpenSpec. The app lets users create courses and decks, study with spaced repetition, and generate cards automatically from text or PDF. It runs locally for now; cloud deployment is the next step.

Technical overview

Architecture

Flashcards is a monorepo with a React frontend and a Spring Boot backend backed by PostgreSQL. The backend is split into domain modules — authentication, courses & decks, flashcards, study mode, AI card generation and PDF import — and calls a pluggable AI provider behind a quota and cost guard. The diagram shows how the parts fit together: orange is own code, purple an external integration and grey data/client.

Architecture diagram of the flashcard app: React frontend, Spring Boot API with domain modules, PostgreSQL, a pluggable AI provider and PDF import
System overview: frontend, the API with its domain modules, the database and the pluggable AI provider.

Key features

Build log

The project is built step by step, one OpenSpec change at a time — each step is planned, reviewed and archived before the next begins. Click a step to read more.

Step 01 – Project foundation · 2026-06-12
  • A monorepo skeleton with Docker Compose + PostgreSQL, a runnable Spring Boot backend and a React/TypeScript frontend with a Vite dev proxy and a health check. The foundation everything later builds on.
Step 02 – Authentication · 2026-06-18
  • JWT in HttpOnly cookies with a CSRF header, a User entity with role and plan, full Spring Security configuration, and login and registration views.
Step 03 – Courses & decks · 2026-06-18
  • CRUD for courses and decks with PUBLIC/PRIVATE visibility (public read, owner-only write), a reusable ownership check, paginated list endpoints, and list/detail views in the frontend.
Step 04 – Flashcard CRUD · 2026-06-19
  • A Card entity (front, back, optional notes), nested /cards CRUD with a card editor, and seed data so the public courses have real, visible decks and cards.
Step 05 – Study mode · 2026-06-19
  • A study session API with a random/round-robin queue, session tracking and a flip-card interface for working through a deck.
Step 06 – AI quota infrastructure · 2026-06-19
  • A pluggable AiProvider interface, an AiUsageLog table and plan gating with monthly token quotas. The cost guard was deliberately built before any AI feature, to keep costs under control.
Step 07 – AI card generation · 2026-06-21
  • Paste text → a guarded AI pipeline → the pluggable AI provider → card drafts with front/back. The user reviews the drafts and saves them in bulk to a deck. Requires PREMIUM or ADMIN.
Step 08 – Spaced repetition · 2026-06-22
  • Per-user state per card (ease factor, interval, repetitions, dueAt) created on first review; the SM-2 algorithm from the grades Again/Hard/Good/Easy; a due queue, a review endpoint and a progress dashboard in the UI.
Step 09 – PDF import · 2026-06-22
  • PDF upload with text extraction via Apache PDFBox, capped to the AI limit and fed into the existing generate → review → save flow (the text is extracted and discarded; file storage is left for the deploy step).
Step 10 – Inline course/deck creation · 2026-06-23
  • The ability to create a course and/or deck right in the save step on the AI generation page, so drafts can be saved without leaving the page (reusing existing endpoints).
Step 11 – Frontend facelift · 2026-06-26
  • A Tailwind v4 design system with five calm, selectable whole-app themes (dark, light, soft pink/green/brown) with persistence and an OS default, reusable UI primitives, and restyled views and navigation.
Step 12 – Session refresh & cleanup · 2026-07-02
  • The frontend now refreshes an expired session automatically: on a 401 it calls the refresh-token endpoint once and retries the original request, so sessions last seven days instead of dying after 15 minutes. Plus some internal cleanup — shared API helpers consolidated in one place and the login check moved into UserService.
Step 13 – Board-based study mode · 2026-07-04
  • A reusable flip-card primitive with a real 3D turn (pure CSS, no animation library; an instant swap for reduced-motion users). Study mode became a board played in rounds: up to six face-up question cards are dealt, you flip them in any order, self-grade each on its back, and every round ends with a tally. The missed cards can be replayed as their own board until everything sticks. Review mode keeps its single-card flow but adopts the same flip.

Lessons

This project has been as much about the way of working as about the code. I've built it spec-driven with OpenSpec and Claude Code: every feature starts as a written change — proposal, design and tasks — that is reviewed and archived before the next begins. That made it easy to keep a clear focus per step and to see afterwards exactly why something was built the way it was.

One concrete lesson was to put the infrastructure before the feature: the quota and cost guard for AI was built before the first AI call, so a pluggable provider could be swapped out without costs running away. Implementing SM-2 for spaced repetition and feeding both pasted text and PDF into the same generate → review → save flow also gave good insight into keeping a growing system coherent rather than cobbled together.