Lifecycle

Understanding how cycles, sessions, and exercises work together in PatternForge.

Training Sets

A training set is a curated collection of exercises. Persisted metadata includes:

• Difficulty — easy, intermediate, advanced, or custom
• Optional source and tags — For display and filtering
• Exercise order — Via the exerciseIds array on the set record

The number of puzzles in a set is the length of exerciseIds.

Cycles

A cycle is a pass through a training set, tracked as a cycle run. Each run includes:

• Status — active or completed (as stored in IndexedDB)
• Cycle number — Which pass through the set (1, 2, 3, …)
• Progress — nextExerciseIndex, totalExercises, solvedCount
• Timing — startedAt, optional completedAt, and totalTimeMs for the cycle
• Started at / completed at — ISO strings

In practice you typically have at most one active cycle per set; completing it moves the run to completed before starting the next cycle.

Sessions

A session is a training period within a cycle. It records:

• Status — active, completed, or abandoned
• Counts — puzzlesAttempted, correctCount, skippedCount
• Active time — activeTimeMs (not a single “total duration” field)
• Optional target — targetPuzzleCount
• Start / end — startedAt, optional endedAt

Sessions are created when you enter training for a cycle; they are updated as you solve (or skip) puzzles and closed when you leave or finish the flow.

Exercises and attempts

An exercise is one puzzle (FEN, side to move, solution line, optional first-move hint).

An exercise attempt (table exerciseAttempts) records:

• Result — correct, incorrect, or skipped
• Duration — durationMs
• Moves — userMoves (UCI); in first-move mode this is typically a single move
• Links — exerciseId, cycleRunId, optional sessionId

Attempts let analytics and review reflect performance over time and across cycles.

Flow

1. Start a cycle — Create or resume an active cycle run for a set
2. Train — Open or continue a session and work through exercises
3. Complete the cycle — When the run is finished, status becomes completed
4. Start the next cycle — New run with an incremented cycle number
5. Track progress — Cycle time, attempts, and session stats in the app

The training philosophy is to improve speed and consistency across repeated cycles while keeping quality high.

Training entry (/app/training)

The Training route is for doing puzzles, not for browsing history.

• If there is an active cycle for the set in settings, Training loads the current exercise and session flow as usual.
• If there is no active cycle, you stay on Training and see an empty state: start a new cycle from Training Sets, or open Progress to review completed cycles. The app does not send you straight to the last cycle summary just because a previous cycle finished.
• After you complete the last exercise of a cycle (or finish via skip), the solve flow can still take you to the cycle summary page for that run.

Progress and Reflection (/app/progress)

Progress shows either your current cycle (when one is active) or Reflection (when none is active).

• Reflection lists completed cycles per training set. You choose a set, then view a table or a simple line chart of total time vs cycle number for that set only (not a single mixed timeline across sets). A median line is computed from the same set’s data. Charts are available when that set has at least two completed cycles.
• Links open the cycle summary for a specific completed run when you want detail; summary and history are opt-in from here, not forced when opening Training.