System Requirements Document for deep-wise

1. Introduction

deep-wise is an Egyptian backgammon game (طاولة) delivered as a first-party web application. The product intent, derived from the authoritative user requirement thread, is to let a player play Egyptian backgammon in two distinct modes:

• Online — a match against a real human opponent.
• Offline — a match against the computer.

The audience is Arabic-first, RTL-reading players who know Egyptian backgammon from the ahwa and the family living room, playing in short sessions on mobile-first devices. The product is a game, not a utility: its identity is carried by its name, its board, and its typography.

2. System Overview

deep-wise is a browser-delivered Egyptian backgammon game with three first-party pages:

• Landing — a public entry surface that explains the Egyptian backgammon game and the difference between online and offline play before any match begins.
• Game Mode — the surface where the player chooses the online or offline mode.
• Game Board — the match surface where the Egyptian backgammon game is played to its result in the chosen mode.

The single accepted active human actor is the لاعب (player). The computer opponent in offline mode is a system actor, not a persona. In online mode, the opposing human player is a materially affected participant whose side of the match must be observable.

2a. Product Interpretation and Delivery Boundary

Current delivery. All three pages are first-party custom UI owned by the application. The Landing page is a public entry surface with no access requirement; it explains the game and the two modes. The Game Mode page is also reachable without an access requirement and presents the online/offline choice. The Game Board page hosts the match itself.

Access ownership. The Planning Scope contract sets access_requirement: none for all three pages, and the accepted journeys do not require a player to privately own or resume durable actor-specific state before playing: a match is initiated, played, and completed within a single session. No application-owned identity, sign-in, or account establishment is therefore introduced. Online matchmaking pairs two players for the duration of a match without requiring either to hold a persistent account.

Online vs. offline ownership. Offline play is fully first-party: the application itself supplies the computer opponent and resolves the match. Online play requires a real-time pairing and match-synchronization service; that service is a supporting system actor behind the Game Board page, not a separate destination and not a persona.

Exclusions. No account management, no social graph, no chat, no tournament ladder, no wagering, and no spectator mode are accepted. No page beyond the three named above is in scope.

2b. Source Content Inventory

Not applicable — no reference directive in this project declares content_source.

2c. Page Content and Component Coverage

Landing

• Information / state. The Egyptian backgammon game identity; a short explanation of what the game is; the distinction between playing online against a real opponent and playing offline against the computer.
• Primary actions. Enter the game to choose a mode (leading to Game Mode).
• Supporting actions. Read the explanation of the two modes; read the rules/overview content.
• Domain entities. Game (Egyptian backgammon), Play Mode (online / offline).
• Component responsibilities.
  • Poster hero: the Arabic word 'طاولة' set at display scale, flush right, with a solid red colour block occupying the right edge; a single line of body copy; two flat rectangular outlined buttons — 'العب أونلاين' (filled black, paper text) and 'العب أوفلاين' (paper with black text and a mustard left border).
  • Rotated micro-label inside the red block reading 'ONLINE / OFFLINE — EGYPTIAN BACKGAMMON'.
  • Two-block split section (red / mustard) presenting the online-vs-offline distinction.
  • Rules/overview section with vector pictograms (dice, doubling cube, checker, bar) drawn as thick black line art on paper.
  • Type marquee band of 'طاولة — طاولة — طاولة' behind the how-to-play section.
• States.
  • Loading: static content; no data fetch required for the entry surface.
  • Empty: not applicable — the page always carries its own explanatory content.
  • Success: the player reads the explanation and activates either mode button, arriving at Game Mode.
  • Error: if the application shell fails to load, a plain paper-ground message with a retry control is shown.
  • Recovery: retry reloads the entry surface; the player can also navigate directly to Game Mode.

Game Mode

• Information / state. The two available modes — أونلاين (online, against a real human opponent) and أوفلاين (offline, against the computer) — presented as two colliding colour blocks meeting at a 6° diagonal.
• Primary actions. Select online mode; select offline mode.
• Supporting actions. Return to Landing to re-read the explanation.
• Domain entities. Play Mode (online / offline), Match.
• Component responsibilities.
  • Red 'أونلاين' block with its oversized Arabic word; mustard 'أوفلاين' block with its oversized Arabic word; the diagonal boundary between them.
  • Focus/hover behaviour: the focused block pushes the diagonal boundary 12px and inverts its text to paper.
  • Mode confirmation: the selected mode is carried forward into the match.
• States.
  • Loading: the mode blocks render immediately; if online availability must be checked, the online block shows a pending state while the check resolves.
  • Empty: not applicable — both modes are always presented.
  • Success: a mode is selected and the player proceeds to Game Board with that mode active.
  • Error: if online mode cannot be started (no opponent available or the pairing service is unreachable), the online block reports the failure in place and the player can retry online or choose offline instead.
  • Recovery: retry online pairing, or switch to offline mode, which does not depend on the pairing service.

Game Board

• Information / state. The Egyptian backgammon board: 24 triangular points in alternating red and mustard with hairline black rules, a bar down the middle, and the four quadrants; the player's checkers and the opponent's checkers; the dice and their pips; the doubling cube; the turn indicator; the match score; the active mode (online or offline).
• Primary actions. Roll the dice; move a checker to a legal destination point; end the turn; accept or offer the doubling cube; start a new match after the result.
• Supporting actions. Read the turn indicator, dice total, and match score in the right-hand rail; read the match result.
• Domain entities. Match, Board, Point, Checker, Dice, Doubling Cube, Turn, Score, Play Mode, Opponent (human or computer).
• Component responsibilities.
  • Board surface: centred, near-square, max 720px, flat printed geometry — no wood texture, no bevel, no gradient.
  • Right-hand rail: dice, turn indicator, and score, with rotated wide-tracked all-caps micro-labels reading like printed margin annotations.
  • Checker movement: a 180ms linear slide with a hard stop and a one-frame black outline flash on the destination point.
  • Dice roll: a six-frame step animation with no easing, landing on the pips.
  • Offline opponent: the application's computer opponent, tagged with the teal offline-AI label.
  • Online opponent: the paired human player's side of the board, synchronized through the match service.
  • Result surface: the match outcome and the option to play again.
• States.
  • Loading: the board renders its geometry immediately; in online mode, a pairing/waiting state is shown until an opponent is present.
  • Empty: in online mode before an opponent is paired, the board is shown with the waiting state and no active turn.
  • Success: the match reaches a result — one side wins — and the result is displayed with the score.
  • Error: a move rejected as illegal is refused and the checker returns to its origin; a lost connection in online mode is reported in the rail with a reconnect option; an unrecoverable online failure offers a return to Game Mode.
  • Recovery: reconnect resumes the online match where it left off; if the match cannot be resumed, the player returns to Game Mode and may start an offline match instead.

3. Functional Requirements

FR-1 — Play Egyptian backgammon As a لاعب, I should be able to play a full game of Egyptian backgammon (طاولة) so that I can complete a match from start to result.

• Provenance: explicit
• Lifecycle: initiated by the player on the Game Board; the match proceeds through turns until one side wins; the result is displayed with the score; the player can start a new match.
• Access: no access requirement.
• Failure/recovery: an illegal move is refused and the checker returns to its origin; the player continues the same match.
• Acceptance: a match reaches a displayed result, and the player can begin another.

FR-2 — Choose the play mode As a لاعب, I should be able to choose between online and offline play so that I can play the way I want.

• Provenance: explicit
• Lifecycle: initiated by the player on the Game Mode page; the selected mode is carried into the Game Board; the mode is visible during the match.
• Access: no access requirement.
• Failure/recovery: if online mode cannot start, the player can retry online or choose offline instead.
• Acceptance: the chosen mode is the mode the match is played in.

FR-3 — Play online against a real human opponent As a لاعب, I should be able to play online against another real player so that I can compete with a person rather than the computer.

• Provenance: explicit
• Lifecycle: initiated by the player selecting online mode; the application pairs the player with another human player; both players take their turns on the shared board; the match reaches a result observed by both.
• Indispensable participant: the opposing human player, who receives the paired match, takes their own turns, and sees the same result.
• Access: no access requirement; pairing is per-match and does not require a persistent account.
• Failure/recovery: if no opponent is available or the pairing service is unreachable, the failure is reported in place and the player can retry or switch to offline.
• Acceptance: two human players complete a match against each other and both see the result.

FR-4 — Play offline against the computer As a لاعب, I should be able to play offline against the computer so that I can play without needing another person or a connection.

• Provenance: explicit
• Lifecycle: initiated by the player selecting offline mode; the application supplies the computer opponent; turns alternate between the player and the computer; the match reaches a result.
• Access: no access requirement.
• Failure/recovery: offline play does not depend on the pairing service; if the application shell fails, the player can reload and start again.
• Acceptance: a full match is completed against the computer with no human opponent involved.

FR-5 — Understand the game and the two modes before playing As a لاعب, I should be able to read what Egyptian backgammon is and how online and offline play differ before I start a match.

• Provenance: required_inference
• Lifecycle: initiated by the player arriving at the Landing page; the explanation and the two mode buttons are presented; the player proceeds to Game Mode.
• Access: no access requirement.
• Failure/recovery: if the entry surface fails to load, a retry control is offered.
• Acceptance: the player can distinguish online from offline play and reach the mode choice from the entry surface.

FR-6 — See the match state during play As a لاعب, I should be able to see the dice, whose turn it is, and the match score while playing so that I can make my move.

• Provenance: required_inference
• Lifecycle: continuously presented on the Game Board's right-hand rail throughout the match.
• Access: no access requirement.
• Failure/recovery: if the online connection is lost, the rail reports it with a reconnect option.
• Acceptance: the turn indicator, dice total, and score are readable at every point in the match.

FR-7 — Resume an interrupted online match As a لاعب, I should be able to reconnect and continue an online match that was interrupted so that a dropped connection does not discard the game.

• Provenance: required_inference
• Lifecycle: initiated by the player reconnecting after a reported connection loss; the match state is restored; play continues from the same position.
• Indispensable participant: the opposing human player, whose board is restored to the same position.
• Access: no access requirement.
• Failure/recovery: if the match cannot be resumed, the player returns to Game Mode and may start an offline match instead.
• Acceptance: after reconnecting, both players continue from the position the match was in.

4. User Personas

لاعب (Player)

Product context. The player is an Arabic-first, RTL-reading person who knows Egyptian backgammon from the ahwa and the family living room. They play in short sessions, most often on a phone, and they expect the game to look and feel like the game they already know — loud, sociable, competitive, and a little theatrical — rather than like a calm utility or a luxury instrument.

Primary goal. To play a complete game of Egyptian backgammon, either against another real person online or against the computer offline, and to see the result.

Distinct accepted responsibilities.

• Reading what the game is and how the two modes differ before starting.
• Choosing the play mode: online or offline.
• Playing the match itself: rolling, moving checkers, and completing the game to its result.
• Reading the match state — dice, turn, and score — while playing.
• Reconnecting and continuing an online match that was interrupted.

Relevant inputs or decisions. The mode choice (online vs. offline); each move decision on the board; whether to continue after a connection loss or switch to offline play.

Interactions with other accepted participants. In online mode, the player is paired with another human player who takes their own turns on the same board and sees the same result. In offline mode, the player's counterpart is the application's computer opponent, which is a system actor rather than a persona.

Observable success. A match reaches a displayed result with the score, and the player can begin another match in either mode.

What makes this role distinct. The player is the only accepted active human actor in the product. Their work is not administration, configuration, or account management — it is the act of playing: choosing how to play, playing the match, and seeing it through to a result. The opposing human player in online mode is a materially affected participant in the same match, not a separate product role with its own responsibilities.

5. Core User Flows

Flow 1 — Play offline against the computer

1. The player arrives at the Landing page and reads the explanation of Egyptian backgammon and the difference between online and offline play.
2. The player activates the 'العب أوفلاين' button.
3. The player arrives at the Game Mode page, where the red 'أونلاين' block and the mustard 'أوفلاين' block meet at a 6° diagonal.
4. The player focuses and selects the 'أوفلاين' block; the diagonal boundary pushes 12px and the block's text inverts to paper.
5. The player arrives at the Game Board, which renders the 24 flat triangular points, the bar, and the right-hand rail with dice, turn indicator, and score. The offline-AI tag is shown in teal.
6. The player rolls the dice; the dice run their six-frame step animation and land on the pips.
7. The player moves a checker; the checker slides 180ms with a hard stop and the destination point flashes a one-frame black outline.
8. The computer opponent takes its turn; the player observes the computer's move on the board.
9. Steps 6–8 repeat until one side wins.
10. The Game Board displays the match result and the score.
11. The player starts a new match, or returns to Game Mode to choose a different mode.

Failure/recovery: if the player attempts an illegal move, the checker returns to its origin and the player continues the same match.

Flow 2 — Play online against a real human opponent

1. The player arrives at the Landing page and reads the explanation of the two modes.
2. The player activates the 'العب أونلاين' button.
3. The player arrives at the Game Mode page and selects the red 'أونلاين' block; the diagonal boundary pushes 12px and the block's text inverts to paper.
4. The player arrives at the Game Board. The board shows a waiting state while the application pairs the player with another human player.
5. The opposing human player is paired into the same match and sees the same board.
6. The player rolls the dice; the dice run their six-frame step animation and land on the pips.
7. The player moves a checker; the checker slides 180ms with a hard stop and the destination point flashes a one-frame black outline. The move is synchronized to the opposing player's board.
8. The opposing human player takes their turn; the player observes the opponent's move on the board.
9. Steps 6–8 repeat until one side wins.
10. The Game Board displays the match result and the score, and the opposing player sees the same result.
11. The player starts a new match, or returns to Game Mode to choose a different mode.

Failure/recovery: if no opponent is available or the pairing service is unreachable, the online block on Game Mode reports the failure in place; the player retries online or selects offline instead.

Flow 3 — Recover an interrupted online match

1. During an online match on the Game Board, the connection is lost.
2. The right-hand rail reports the connection loss and offers a reconnect control.
3. The player activates reconnect.
4. The match state is restored and the board returns to the position the match was in; the opposing human player's board is restored to the same position.
5. Play continues from that position.

Failure/recovery: if the match cannot be resumed, the player returns to Game Mode and may start an offline match instead.

6. Visuals, Colors and Theme

Muse and headline. Paula Scher — Type as the board: an Egyptian backgammon table built out of poster-scale Arabic lettering.

Mode. Light mode.

Colour tokens (exact hex, by role).

Proportion. Roughly 55% paper, 25% red, 12% mustard, 8% teal/black rules.

Typography.

• Headings: Anton at poster scale, uppercase for Latin, with matching heavy weight for Arabic display via Cairo Black; Anton for numerals and Latin labels.
• Body: Cairo.
• Micro-labels: small, all-caps, wide-tracked, in Cairo SemiBold.
• Scale: 1.333 modular — display 96px desktop / 52px mobile (clamp(52px, 11vw, 96px)), h1 64/40, h2 40/28, h3 28/20, body 18/16, label 12/11 tracked 0.12em.
• Headlines stack in tight leading (0.9), flush-right for RTL, sometimes rotated 90° along a board edge.

Shape language. Hard edges everywhere — no border radius on blocks, cards, or buttons except a 2px chamfer on the dice. Colour blocks are rectangles that collide and overlap rather than nest. The board is the one place with strict geometry: 24 triangular points, hairline black rules between quadrants, a bar down the middle. Diagonal bands of type cut across section boundaries at 6° and −6°. Buttons are flat rectangles of pure colour with a 2px black outline and no shadow.

Spacing rhythm. Poster grid, asymmetric. The landing hero is a 12-column grid where the headline occupies columns 1–9 and bleeds off the right edge in RTL, with a solid red block filling columns 10–12 full-height. Sections alternate: full-bleed type section, then a two-block split (red / mustard), then a dense board-preview section. The Game Mode page is two colliding colour blocks meeting at a 6° diagonal. The Game Board page is a centred, near-square board at max 720px with a narrow right-hand rail for dice, turn indicator, and score.

Imagery style. Typography is the image — no photography in the hero. Supporting imagery is high-contrast, two-colour: a halftone black-and-white photo of a Cairo ahwa table with a backgammon board, cropped hard to the grid, tinted red on one side of a split. Vector pictograms for the rules section (dice, doubling cube, checker, bar) drawn as thick black line art on paper. The board itself is drawn, not photographed: flat colour triangles, black rules, mustard and red checkers with a single white pip highlight.

Forbidden. Blue or indigo primary accents on white; gradient blobs, glassmorphism, frosted panels, or soft drop shadows on cards; rounded pill buttons and 16px+ card radii; centred headline + subtext + single CTA hero composition; wood-texture, felt, or photoreal 3D board renders; Inter, Roboto, Poppins, system-ui, or any neutral geometric sans for headings or body; neon or glow effects on dice, checkers, or board points; any decorative element that overlaps readable Arabic text or a control at 375px, 768px, or 1280px.

7. Signature Design Concept

The clipped word. The public entry is a full-viewport RTL poster. A solid Scher-red block covers the right 40% of the screen edge to edge, top to bottom. On the paper ground to its left, the Arabic word 'طاولة' is set in Cairo Black at clamp(52px, 11vw, 96px), stacked in two lines, flush right, bleeding off the right edge so the final letter is clipped by the red block — the type and the colour block are the same object, not a headline over a background. Below it, a single line of body copy in Cairo 18px, then two flat rectangular buttons side by side, each with a 2px black outline: 'العب أونلاين' filled black with paper text, and 'العب أوفلاين' as paper with black text and a mustard left border. Inside the red block, rotated 90°, a mustard all-caps micro-label reads 'ONLINE / OFFLINE — EGYPTIAN BACKGAMMON'. No gradient, no blob, no centred stack, no floating card. At 375px the red block becomes a bottom band 96px tall and the headline stacks to three lines at 52px, still fully inside the viewport.

The concept recomposes only accepted content and controls: the game's name, the explanation of the two modes, and the two mode entry buttons.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: flat

Landing Hero Motion Brief.

• Focal subject: the Arabic word 'طاولة' at display scale, flush right, clipped by the solid red block on the right edge.
• Input → transformation → outcome thesis: as the entry surface loads, the word 'طاولة' slides in from the right while a solid red block wipes across behind it (300ms, cubic-bezier(0.2,0.8,0.2,1)); the outcome is the composed poster frame in which the type and the colour block are one object.
• Motion vocabulary: type marquees and colour-block wipes, nothing bouncy.
• Composed first frame: the red block already occupying the right 40%, the word 'طاولة' arriving into it, the body line and the two outlined mode buttons settling in place beneath.
• Reduced-motion state: all motion stops and elements appear in place; the marquee band stops and wraps into static rows.

Mode page motion. Hovering or focusing a mode block pushes the diagonal boundary 12px and flips that block's text to paper.

Board motion. A checker move is a 180ms linear slide with a hard stop and a one-frame black outline flash on the destination point — mechanical, like a stamp. The dice roll is a six-frame step animation with no easing, landing on the pips.

Reduced motion. All motion stops under prefers-reduced-motion and elements appear in place.

9. Non-Functional Requirements

NFR-1 — Arabic-first RTL layout. The interface is Arabic-first and right-to-left; headlines are flush-right and the layout mirrors accordingly. Provenance: explicit (creative direction).

NFR-2 — Mobile-first responsiveness. The game is playable at 375px, 768px, and 1280px. Headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container at every one of these widths, wrapping or scaling to fit, and no other element covers any part of them. Provenance: explicit (creative direction).

NFR-3 — Reduced-motion support. All motion stops under prefers-reduced-motion; elements appear in place and the marquee wraps into static rows. Provenance: explicit (creative direction).

NFR-4 — Online match synchronization. Online matches require real-time synchronization of board state between two human players, including restoration of the shared position after a reconnect. Provenance: required_inference (from the accepted online-play requirement).

NFR-5 — Offline independence. Offline play against the computer must not depend on the online pairing or synchronization service. Provenance: required_inference (from the accepted offline-play requirement).

NFR-6 — No account requirement. No page requires sign-in or account establishment; a match is initiated, played, and completed within a session. Provenance: explicit (Planning Scope access contract).

10. Tech Stack

• Frontend: React (web), Arabic-first RTL, mobile-first responsive layout.
• Backend: Python / FastAPI, providing the online pairing and match-synchronization service.
• Storage: match state for active online matches, sufficient to restore a shared position after a reconnect.
• Containerization: Docker / docker-compose for local and deployment packaging.

Kubernetes is not required by any accepted requirement and is therefore not included.

11. Assumptions and Constraints

• A-1. The single accepted active human persona is لاعب; no additional personas are introduced. (From the Planning Scope persona contract.)
• A-2. The page inventory is exactly Landing, Game Mode, and Game Board; no page is added, removed, merged, split, renamed, or reordered. (From the versioned page contract.)
• A-3. All three pages have no access requirement; no application-owned identity, sign-in, or account management is introduced. (From the Planning Scope access contract.)
• A-4. The computer opponent in offline mode is a system actor, not a persona. (Required inference.)
• A-5. The opposing human player in online mode is a materially affected participant in the same match, not a separate product role. (Required inference.)
• A-6. Online pairing is per-match and does not require either player to hold a persistent account. (Required inference from the no-access contract.)
• A-7. The rules/overview content on the Landing page is explanatory content about Egyptian backgammon and the two modes; it does not introduce a separate rules destination. (Required inference.)
• A-8. No account management, social graph, chat, tournament ladder, wagering, or spectator mode is in scope. (Exclusion.)

12. Glossary

• طاولة (Tawla) — Egyptian backgammon; the game this product delivers.
• لاعب (Player) — the single accepted active human persona; the person who plays the game.
• أونلاين (Online) — the play mode in which the player is matched against another real human player.
• أوفلاين (Offline) — the play mode in which the player plays against the computer.
• Point — one of the 24 triangular positions on the backgammon board.
• Bar — the central divider of the board, between the quadrants.
• Checker — a playing piece; red for player 1, mustard for player 2.
• Doubling Cube — the cube used to raise the stakes of a match.
• Match — a single game of Egyptian backgammon played to a result.
• Game Mode — the page where the player chooses between online and offline play.
• Game Board — the page where the match is played to its result.
• Landing — the public entry page that explains the game and the two modes.