FSRSpring Vocabulary
A smart, automated vocabulary learning system powered by the Free Spaced Repetition Scheduler (FSRS) and Spring Boot.
FSRSpring Vocabulary is a modern, modular web application designed to help users master vocabulary efficiently. By integrating the state-of-the-art FSRS (Free Spaced Repetition Scheduler) algorithm, this project dynamically calculates optimal review times to minimize daily workload while maximizing long-term retention.
Key Features
FSRS-Driven Scheduling
Precise, algorithmic spaced repetition based on active memory states, adapting automatically to user performance rather than relying on static intervals.
|
Automated Word Enrichment
Built-in pipeline leveraging Datamuse and Dictionary APIs to fetch and enrich word definitions, pronunciations, and practical usage examples.
|
Comprehensive Analytics
Data-driven tracking of learning progress, mastery levels, review logs, and daily streaks to provide complete insight into retention metrics.
|
Modular Monolith Architecture
Strictly bounded contexts with clear inter-module communication, isolating domain logic from infrastructure to ensure high maintainability.
|
Architecture & Technology Stack
This project adheres to a Modular Monolith architectural style. Inter-module communication flows through explicit public service interfaces to keep domains cleanly separated.
Core Stack
- Backend: Java 17, Spring Boot 3, Spring Data JPA, Spring Security
- Database: MySQL 8.4, Redis 7 (session store)
- Frontend (Modern): Next.js 15, React, Tailwind CSS
- Frontend (Legacy): Vanilla HTML/CSS/JavaScript with Tailwind CSS
Domain Modules
word-management: Word CRUD operations, metadata, API enrichment, imports.
review-scheduling: FSRS state transitions, next review date calculations.
learning-session: Quiz workflows, flashcard learning orchestration.
progress-analytics: Mastery analytics, user streaks, and retention metrics.
Getting Started
Prerequisites
Option A — Docker Compose (recommended)
Spins up the full stack: Spring Boot API, Next.js frontend, MySQL, Redis, and LibreTranslate.
cp .env.example .env # edit credentials if needed
docker compose up --build
docker compose down # stop containers
docker compose down -v # stop and delete volumes (wipes database)
Option B — Run backend locally (dev mode)
Use this when you want fast iteration on the backend without rebuilding Docker images. The infrastructure services (MySQL, Redis) still run in Docker.
Step 1 — Start infrastructure:
docker compose up -d mysql redis libretranslate
Step 2 — Copy and configure environment:
cp .env.example .env # edit credentials if needed
Step 3 — Run Spring Boot with the local profile:
macOS / Linux (recommended — auto-frees port 8080 if occupied):
./scripts/dev.sh
Or manually:
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
Windows (PowerShell):
.\mvnw.cmd spring-boot:run "-Dspring-boot.run.profiles=local"
The local profile (src/main/resources/application-local.properties) connects to:
- MySQL on
localhost:3307
- Redis on
localhost:6380
scripts/dev.sh also starts infrastructure services automatically and stops any Docker container or process occupying port 8080 before launching.
Step 4 — Start the frontend (optional):
cd frontend
corepack enable
pnpm install
SPRING_API_BASE_URL=http://localhost:8080 pnpm dev
Environment variables
Copy .env.example to .env and fill in the required values:
| Variable |
Description |
Default |
MYSQL_USER / MYSQL_PASSWORD |
MySQL credentials |
fsr_user / fsr_pass |
REDISPASSWORD |
Redis password |
fsr_redis_pass_123 |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
OAuth2 Google login |
— |
JWT_SECRET |
32+ byte secret to enable local JWT login |
— |
YOUTUBE_API_KEY / NEWS_API_KEY |
External content APIs |
— |
Testing & Quality Assurance
The project includes isolated unit tests for FSRS state transitions, contract tests for scheduler interfaces, and comprehensive integration tests for APIs.
macOS / Linux:
./mvnw clean test
Windows:
.\mvnw.cmd clean test
Development Guidelines
To ensure the project remains scalable, performant, and robust, adhere to the following principles when contributing:
- Strict FSRS Scheduling: Never bypass the FSRS engine. All scheduling decisions and review dates must be calculated via core algorithmic variables.
- Architectural Boundaries: Controllers must never call repositories directly. Domain logic lives exclusively in domain classes and service layers. Zero cross-module repository leakage is permitted.
- UI/Accessibility Standards: Ensure strict WCAG AA compliance (minimum contrast ratio 4.5:1), complete keyboard navigability, and maintain clean separation of CSS Custom Properties for theme support.
- Design Documentation: Review the internal
CLAUDE.md specification for deeper insights into the project's Modular Monolith direction and algorithmic optimizations.
Continuous Integration / Continuous Deployment
A fully automated CI/CD pipeline is available at .github/workflows/ci-cd.yml:
- Continuous Integration: Triggers on pull requests and pushes to the
main branch. Executes comprehensive matrix tests across ubuntu-latest, macos-latest, and windows-latest running Java 17.
- Continuous Deployment: On a successful merge or push to
main, the workflow builds and distributes the respective Docker image to the GitHub Container Registry (ghcr.io).