Superapp / Product requirements / chess

Gambit Club — product requirements

Version 1.810 features34 requirements16 Must Open appJSONMarkdown

Gambit Club is a small online chess club. Players face deterministic bots (Levels 1 to 3) or a friend on one screen, move by click or typed notation, import and export FEN and PGN, solve mate puzzles, replay finished games and track an Elo rating. Guests can play casual games and solve puzzles; rated games, History and Profile need an account.

Problem. Players need a chess board that applies the rules of the game exactly and predictably, with ratings that move in the right direction, so that results and history can be trusted.

Users

Goals

Out of scope

Contents

Sign-in and access

Account sign-in, guest access and the pages that require an account.

FR-AUTH-01
Must
A member signs in with username and password and lands on the Play screen showing their name and rating.
  • The top bar shows the display name, "Rating <n>" and a "Sign out" button
  • The "Rated game" option becomes enabled
FR-AUTH-02
Should
Sign-in reports missing and wrong input separately and never signs the user in on error.
  • No username: "Enter your username" with focus in the username field
  • No password: "Enter your password"
  • Wrong credentials: "Wrong username or password" and the login screen stays open
  • "Continue as guest" opens Play with the top bar showing "Guest"
FR-AUTH-03
Could
History and Profile are available to signed-in members only; Puzzles stay open to guests.
  • Guest History: "Sign in to see your games"
  • Guest Profile: "Sign in to see your profile"

Game lobby

Choosing opponent, level, colour and clock before a game.

FR-LOB-01
Must
The lobby offers every game option with fixed defaults and navigation to the four areas of the club.
  • Heading "New game"; Opponent: Bot / Hot-seat; Bot level: Level 1, 2, 3; Your colour: White / Black; Time control: 5+0, 3+2, Untimed
  • Defaults: Bot, Level 1, White, Untimed
  • Sidebar: Play, Puzzles, History, Profile
FR-LOB-02
Must
Rated play is locked for guests and available to signed-in members against bots.
  • Guest: "Rated game" is disabled with the note "Sign in to play rated games." and a Sign in link
FR-LOB-03
Must
Starting a game opens the board with a heading that names the game and the side to move.
  • Bot game: "Game vs Bot L<level>", status "Your move", "No moves yet"
  • Hot-seat game: "Hot-seat game", "White to move"
  • Starting a new game while one is in progress asks for confirmation ("Leave game")

Board and move entry

Click and typed moves, visual aids and notation.

FR-BRD-01
Must
Clicking one of the player’s own pieces selects it and marks only its legal destination squares; clicking it again clears the selection.
  • The knight on g1 at the start offers f3 and h3 only
  • Clicking an opponent piece shows no dots
FR-BRD-02
Must
Moves may be typed in algebraic notation or coordinate form; an unreadable or illegal move is rejected without changing the position.
  • "e4", "Bc4", "O-O" and "e2e4" are accepted when legal
  • Otherwise the inline error is: Illegal or unreadable move "<text>"
FR-BRD-03
Must
The move list is written in standard algebraic notation, numbered per full move.
  • Captures use x (Nxe4, exd5), check +, mate #, castling O-O, promotion a8=N
  • Black’s move after a break reads "2. ... Qh4#"
FR-BRD-04
Should
The king in check glows on the board and in the status line, and the glow clears when the check is resolved.
  • Status reads "Black to move, in check"
  • After the check is parried the status reads "White to move" with no glow
FR-BRD-05
Could
The last move is tinted gold on both its squares and only those squares.
FR-BRD-06
Could
Each player strip shows captured pieces and a "+N" material difference for the side ahead.
  • Equal material shows no "+" on either side
  • After 1.e4 d5 2.exd5 White’s strip shows one black pawn and "+1"
FR-BRD-07
Could
The board can be flipped by the "Flip board" button or the F key; a game played as Black starts flipped.
  • Unflipped: ranks 1 to 8 in the left column (8 on top), files a to h along the bottom
  • Flipped: Black at the bottom, rank 1 on top, files run h to a

Rules of chess

Exact enforcement of special moves and game endings.

FR-RUL-01
Must
A king may not castle out of, through or into an attacked square.
  • With a bishop attacking f1, the king on e1 has no destination dots and "O-O" is rejected as illegal
  • Once the diagonal is blocked the position is playable again
  • Castling with no attacked square is legal: O-O puts the king on g1 and the rook on f1
FR-RUL-02
Must
En passant is legal only on the move immediately after the double pawn step.
  • 1.e4 a6 2.e5 d5 3.exd6 captures the d5 pawn
  • If any other move is played first, exd6 is rejected as illegal
FR-RUL-03
Must
A pawn reaching the last rank opens a "Promote pawn to" dialog offering Queen, Rook, Bishop and Knight, and the chosen piece is placed.
  • Escape closes the dialog and leaves the pawn unmoved
  • Choosing Knight on a8 gives a white knight and the notation a8=N
FR-RUL-04
Must
A side with no legal move and not in check has drawn by stalemate, never lost.
  • Status "Draw by stalemate"; the move box is replaced by "New game" and "Export PGN"
FR-RUL-05
Must
A side in check with no legal move is checkmated and the opponent wins.
  • Status "<Side> wins by checkmate"
  • Casual games show "Casual game, no rating change"

Bot opponents

Deterministic replies for Levels 1 to 3.

FR-BOT-01
Must
The Level 1 bot answers 1.e4 with a5 and 2.Bc4 with a4, so a fixed opening is repeatable.
  • The bot reply appears automatically and the status returns to "Your move"
FR-BOT-02
Should
Bot replies are fixed for a given sequence of moves, and Level 3 differs from Levels 1 and 2 on the third move.
  • After e4, Nf3, d4 Levels 1 and 2 reply a5, a4, a3
  • Level 3 replies a5, a4, b6
  • When the user plays Black every bot opens with Na3
FR-BOT-03
Could
Undo is available only in casual games against a bot and takes back the last move together with the bot reply.
  • Undo is disabled before any move and in hot-seat games
  • After e4 a5, Undo restores the start position with "No moves yet"

Resign, draw and clocks

Ending a game by resignation or agreement, and time controls.

FR-END-01
Should
Resigning asks for confirmation first; Cancel keeps the game going.
  • Dialog "Resign this game?" with Cancel and Resign, focus on Cancel
  • Confirming gives "<Opponent side> wins by resignation"
FR-END-02
Should
Draw offers are confirmed first; the bot declines early offers and a hot-seat opponent may accept or decline.
  • Confirm dialog "Offer a draw?"
  • Bot: "The bot declined: too early for a draw"
  • Hot-seat: the callout "<Side> offers a draw" with Accept and Decline; Accept gives "Draw by agreement", Decline continues the game
FR-END-03
Could
Each side has a clock matching the chosen time control, and the side to move counts down.
  • 5+0 starts both clocks at 5:00; 3+2 at 3:00
  • Untimed shows no clocks

Ratings

Elo changes for rated games against bots.

FR-RAT-01
Must
A rated win raises the rating and a rated loss lowers it; the result card shows the new rating and the signed change.
  • Rated win over Level 1 from 1340 shows "Rating 1341 (+1)"
  • Resigning a rated Level 2 game from 1340 shows "Rating 1314 (−26)"
FR-RAT-02
Must
The Profile reflects every rated result immediately; casual games never change the rating.
  • After the win above: Rating 1341, Rated games 8, Record 3W 2D 3L
  • After the resignation above: Rating 1314, Rated games 8, Record 2W 2D 4L, Last change −26

Import and export

FEN and PGN in and out.

FR-IMP-01
Should
Export PGN shows the moves played in standard notation, and Copy FEN confirms with a toast.
  • After e4 e5 Nf3 the text contains 1. e4 e5 2. Nf3
  • The exported text lists all moves in the order played
FR-IMP-02
Should
Import accepts a FEN or PGN and starts a hot-seat game at that position; empty or invalid input keeps the dialog open with an error.
  • Empty: "Paste a FEN or PGN first"
  • Invalid FEN: an error under the text box
  • Valid input: heading "Imported position" and play continues from it, e.g. a 5-ply PGN ends with Bb5 and "Black to move"

Puzzles

Eight mate puzzles with forced replies.

FR-PUZ-01
Should
Eight puzzles are listed and solving one marks it Solved.
  • The list runs from "Back-rank finish" to "King steps up", none Solved initially
  • A wrong move shows "Try again" and resets; the right move shows "Correct" and offers Restart and Next puzzle
FR-PUZ-02
Could
Multi-move puzzles play the forced reply and expect the follow-up mate.
  • "Queen sacrifice on b8": Qb8+ shows "Correct. Black replied Rxb8, now find the mate"; Rxb8 completes it
  • "Next puzzle" opens "King steps up"

History, replay and profile

Finished games, replay and rating chart.

FR-HIS-01
Must
History lists the member’s finished games newest first and can be filtered by outcome.
  • Seeded member: 12 rows; Wins 3, Draws 4, Losses 5
  • The newest row is a loss to Bot L3 by resignation on Sep 24, 2026; the oldest is a win over Bot L1 by checkmate on Sep 2, 2026
  • A member with no games sees an empty state
FR-HIS-02
Could
A finished game can be replayed move by move with buttons and keyboard.
  • Replay opens at the start position; Left arrow steps back, Home returns to the start
  • An unknown game id shows "Game not found"
FR-HIS-03
Could
Profile shows rating, rated games, record and last change, with a rating line chart.
  • Seeded member: Rating 1340, Rated games 7, Record 2W 2D 3L, Last change −14; line from 1400 to 1340 over 8 points
  • A member with no games sees an empty chart state

Non-functional requirements

NFR-01
Should
The app fits a 390 px phone with no horizontal scroll, a bottom tab bar replacing the sidebar and the board filling the width with 16 px margins.
  • Dialogs fit the screen; puzzle cards stack in one column

Glossary and rules

Hot-seatTwo players taking turns on one screen.
Rated gameA game against a bot whose result changes the member’s Elo rating.
FEN / PGNStandard text formats for a position and for a list of moves.