ChessSRS Knowledge Base
The complete technical reference manual for ChessSRS: architecture, spaced repetition mathematics, graph traversal, and formal specifications.
Why ChessSRS?
Most chess opening trainers query an engine evaluation bar to decide if your move was acceptable. ChessSRS asks what you prepared. Your repertoire is the authoritative answer key, including intentional sidelines, gambits, and traps set for natural opponent mistakes.
Standard flashcard algorithms (such as SM-2 or naive Leitner boxes) were designed for isolated vocabulary cards. When applied to chess move trees, they fail catastrophically: moves depend strictly on prior moves, transpositions reconnect different lines to the same board state, and an opponent blunder branches into new opportunities. ChessSRS bridges this gap by combining the empirical FSRS (Free Spaced Repetition Scheduler) with a custom Graph-Aware Review Coordinator.
The entire critical path—from move input, dartchess validation, repertoire lookup, SRS schedule update, to board animation—executes 100% locally in-memory and in SQLite on your device. Zero servers, zero telemetry, zero account required.
Documentation Matrix
Explore the complete architectural and mathematical specifications of ChessSRS:
Engineering & Architectural Principles
ChessSRS is engineered under strict invariants designed to ensure software longevity and correctness:
| Principle | Rule | Implementation Mechanism |
|---|---|---|
| Pure Domain | Zero UI or database dependencies in chess logic. | Isolated in lib/src/domain/, verified by automated banned-API gate G03. |
| Single Chess Representation | dartchess is the sole chess geometry engine. |
Never introduce competing chess parsers or custom move representations. |
| Variation Preservation | User variations are never flattened or pruned on import. | Multi-chapter PGN tree parser with recursive annotation branches (RAV). |
| Deterministic Clocks | Scheduling calculations must never read wall-clock time directly. | Injected Clock interfaces ensure 100% reproducible time tests. |
| Anti-Weakening Tripwires | No deleted assertions, skipped tests, or loosened tolerances. | Gate G08 diffs git commits to reject test-weakening patterns before merge. |
Recommended Reading Paths
Select the path best aligned with your exploration goals:
- For Chess Learners & Players: Start with Product Vision and FSRS Spaced Repetition to understand review intervals, and Graph-Aware Coordinator to see how transpositions and mistakes are handled.
- For Software Architects: Read System Architecture to inspect layer boundaries and Lichess mobile fork mechanics, followed by Domain Model & Schemas.
- For Contributors & Developers: Follow the Developer Guide to set up the FVM toolchain, run codegen, and pass the Testing & Quality Gates.