Functional Overview

Dice Chess Lab is a premium, state-of-the-art analysis and training platform for Dice Chess—a dynamic chess variant where standard rules are modified by random dice rolls that restrict legal moves.

This overview guides you through the application’s key functional areas, explaining how to browse and filter historical matches, practice in interactive simulator modes, curate tactical puzzles, and manage the system.

🔍 1. Game Browser Mode

The Game Browser is the analysis hub of Dice Chess Lab. It enables players to explore historical matches, analyze complex turn sequences, bookmark critical positions, and share deep-linked board states.

Search & Filtering

The dashboard features an advanced, multi-parameter search interface to slice and dice the global match database:

Player Filtering: Search matches specifically played by white or black players (supports autocomplete).
Game Type: Filter by time control categories (e.g. Blitz, Rapid, Classical).
Bet Range: Filter matches by the amount of in-game currency or points wagered.
Chronological Sorting: Order games by date played to follow recent opening trends.

Interactive Analysis Board

Opening any match launches the high-performance analysis layout:

Interactive Ply Navigation: Move-by-move playback utilizing a responsive Chessground board.
Multi-Move Turn Visualization: Unique indicators displaying the specific Dice Roll (e.g., King, Knight, Pawn) that governed each turn, along with bank indicators and time constraints.
Alternative Move Branching: Explore alternative variations directly on the board.

Bookmark Positions

Encountered a beautiful tactical shot or a critical opening mistake?

Click the Bookmark (📌) button to capture the active board position.
Save with custom text annotations or notes.
The position, FEN string, dice roll, played moves, and notes are saved to your personal profile for future review.

🎯 2. Training Simulator Mode

The Training Simulator turns passive game viewing into an active learning experience. It implements a sophisticated “Guess the Move” loop that challenges you to play like the masters.

”Guess the Move” Playback

Instead of simply clicking through moves, the simulator hides the upcoming ply:

The simulator rolls the dice and sets up the board.
You must input the move you believe was actually played in the game.
The engine instantly evaluates your input against the played moves list.
Provides real-time feedback: Perfect Match (all micro-moves correct), Partial Match, or Incorrect.

Features & Integrations

Share Training Progress: Generate and share dedicated training simulator links so others can attempt the exact same sequence of guessable moves.
Auto-Flip Board: Automatically flips the board perspective to match your active training color, ensuring natural visualization.
Custom Puzzle Export: If you fail a guess or identify an exceptionally educational turn, click Save as Custom Puzzle. This exports the position, FEN state, dice roll, and correct solution directly to the global/personal Training Puzzle Bank.

🧩 3. Puzzle Solver Mode

The Puzzle Solver focuses on isolated tactical training, challenging you to find the correct multi-move sequence given a specific dice roll.

Interactive Solver

Load hand-curated tactical puzzles or automated scenarios generated from player mistakes in real-time.

Multi-Move Validation

Puzzles are validated by the backend engine, enforcing that all micro-moves (e.g. Knight + Bishop) match the optimal solution.

Performance Analytics

Track your success and failure rates. Every attempt is logged with millisecond precision to calculate your accuracy.

👑 4. Administration Dashboard

Dice Chess Lab includes a secure, comprehensive Admin Panel giving administrators full control over users, data pipelines, and background execution.

User Management & Closed Beta

The platform implements a controlled onboarding flow for closed beta:

Pending Approval Gate: New users who authenticate via Google OAuth2 are held in a pending state with no platform access until approved.
Approval Actions: Admins can instantly approve new users with a single click.
Role Management: Demote or promote users to the ADMIN role.
Access Blocking: Temporarily or permanently block/unblock users from accessing platform APIs.

Advanced User Statistics

The admin panel displays a rich analytics dashboard for each user:

Registration Date: The exact date and time the user registered.
Last Login Date: Formatted timestamp showing when the user was last active.
Puzzles Solved: Displays a ratio of solved vs. attempted puzzles (e.g., 🧩 Puzzles: 15 / 22).
Trainer Simulator Runs: Total count of active “Guess the Move” simulator attempts.

Safe User Deletion

When a user requests account removal, Admins can trigger Safe Delete:

Initiates a database-level cascading cleanup.
Instantly purges the user profile, all favorite games, bookmark positions, simulator training logs, and puzzle attempts safely.
Admins are prevented from deleting their own active profile.

Data Ingestion Control

Triggers and monitors long-running background tasks via a centralized queue:

Metadata Sync: Crawl external server lists to fetch new matches.
Moves Sync: Fetch deep turn-by-turn ply histories for ingested matches.
Tasks Progress: Live progress indicators, parameters tracking, and error reporting.

👤 5. Profile & Settings

Your profile controls authentication, display settings, and mock parameters.

Authentication State

Secured by standard Google OAuth2 + JWT cookies.
Easy sign-in and sign-out controls.

Preference Configurations

Customize your board aesthetics and display logic:

Flip Board: Manually toggle black or white perspective.
Visual Markings: Toggle showing legal moves highlights, threat paths, or last move highlights on the board.
Board Coordinates: Show or hide rank and file notations.

Development Mock Auth

For testing in offline or local environments, developers can bypass Google OAuth:

Configure MOCK_AUTH=true in the backend environment.
Toggle mock user credentials instantly on the login page to bypass active network calls.