System Requirements Document for gorilla-tag-mobile

1. Introduction

gorilla-tag-mobile is a mobile multiplayer movement game in the style of Gorilla Tag: players run and climb through a shared low-poly jungle world using touch controls, and they play together in shared rooms where they can see and interact with other players in the same session. The product is delivered as a first-party web application that runs in a phone browser, with an application-owned backend that keeps room state and player presence in sync across everyone in a room.

The audience is young, social, drop-in phone players who want a loud, physical, tag-you're-it playground rather than a polished productivity interface. The emotional register is streetwear-adjacent, industrial and a little chaotic: concrete grounds, safety-orange accents, hazard tape, quoted wordmarks and garment-tag room labels.

This document is the System Requirements Document for the project. It specifies the current product intent, the accepted pages and their access boundaries, the functional requirements, the two accepted personas, the end-to-end journeys, the visual and motion direction, and the technical delivery shape.

Success Criteria

• A new player can land on the anonymous Landing page, understand that this is a mobile Gorilla Tag-style game with touch locomotion and shared rooms, and reach enrollment without prior knowledge.
• A player can enroll or verify on the Login page and arrive at a protected destination (Rooms or Play) with a persistent in-game identity.
• A player can browse existing rooms, join one, and immediately see and be seen by other players in the same session.
• A Room Host can create a room, choose a mode or map, and have other players join it.
• Touch locomotion — running and climbing — works on a phone and is the primary way a player moves through the world.
• The game is playable on mobile devices at 375px, 768px and 1280px viewports without readable text or controls being cropped or covered.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The product is a first-party mobile web game. The React frontend renders four application-owned pages — Landing, Login, Play and Rooms — and the shared FastAPI backend serves the game APIs and multiplayer session service. Redis holds live room state and presence so that every player in a room sees the same session; MariaDB holds application-owned persistent data such as player identity and durable room records.

Access is layered. Landing and Login are anonymously reachable: Landing is the public entry surface that explains the game, and Login is where a player establishes identity for the first time or verifies a returning identity. Rooms and Play require login, because a player's in-game identity, room membership and presence must remain bound to the correct participant across sessions. There is no differentiated permission model: every logged-in player can browse rooms, create a room, join a room and play. The Room Host role describes who created a given room, not a privileged account tier.

The reference to Gorilla Tag is a style and domain reference only — a mobile movement game with climbing and multiplayer rooms. No Gorilla Tag assets, branding, names or copy are used. The current scope is the four pages above and the multiplayer loop they support. Nothing beyond that loop — no cosmetics economy, no progression system, no social feed, no voice chat, no matchmaking ranking — is part of this delivery.

2c. Page Content and Component Coverage

Landing

• Information and state: Anonymous public entry. Explains that this is a mobile Gorilla Tag-style game, that movement is touch-based (running and climbing), and that players share multiplayer rooms. No player-specific state is shown.
• Primary actions: JOIN A ROOM (solid orange rectangle, pinned bottom-left of the hero band) leads toward the protected room flow, routing through Login when identity is not yet established. CREATE ROOM (black outline button beside it) leads toward room creation, likewise routing through Login when needed.
• Supporting actions: A path into Login for returning players who want to verify first.
• Domain entities: None owned here; the page presents product intent only.
• Component responsibilities:
  • Full-bleed concrete hero band occupying the top ~70vh.
  • Oversized quoted wordmark GORILLA TAG in Archivo Black, stacked on two lines, spanning the left 9 columns, with MOBILE in a black punched garment-tag chip tucked under the baseline.
  • Hazard-stripe band running the full viewport width beneath the headline.
  • Single dramatic device mockup on the right: a phone held edge-on at a slight angle, screen showing the low-poly jungle with a gorilla silhouette mid-climb, bleeding off the right edge and partially cropped by the viewport.
  • Ticker tape of quoted verbs (RUN CLIMB TAG JOIN separated by asterisks) along section seams.
  • Exposed 1px grid lines at column boundaries behind the headline and content.
• States:

• Loading: static shell renders immediately; no data dependency.
• Empty: not applicable.
• Success: hero, CTA pair and ticker render; CTA routes to Login when unauthenticated, or to Rooms when a session already exists.
• Error: if the session check fails, CTAs fall back to the Login route rather than blocking the page.
• Recovery: the player can always reach Login from the hero CTA pair.
• Responsive: at 375px the right rail drops below the headline, the wordmark scales via clamp(64px, 12vw, 168px), and the CTA pair stacks without clipping.

Login

• Information and state: Anonymous identity-access surface. Two modes: enroll (first use) and verify (returning). Shows which mode is active and any validation feedback.
• Primary actions: Submit enrollment credentials to create a player identity; submit returning credentials to verify an existing identity.
• Supporting actions: Switch between enroll and verify modes; return to Landing.
• Domain entities: Player identity (display name and credentials), session.
• Component responsibilities:
  • Mode switch between enroll and verify, styled as hard-cornered black/orange rectangles with offset 3px shadow.
  • Credential fields with 11px uppercase micro-labels at 0.12em tracking.
  • Submit control with hazard-stripe underline.
  • Inline validation and error region.
• States:
  • Loading: submit control shows a pending state while the backend responds.
  • Empty: fields blank with micro-label placeholders.
  • Success: on enroll, identity is created and the player is routed to Rooms; on verify, the session is restored and the player is routed to Rooms (or back to the destination they were heading toward).
  • Error: invalid credentials, duplicate display name on enroll, or network failure show an inline message and keep the entered values so the player can correct and retry.
  • Recovery: the player can switch modes or retry without losing the page.

Rooms

• Information and state: Protected. Lists currently available shared rooms with room code, player count and mode, and shows the player's own current room membership if any.
• Primary actions: Join an existing room; create a new room.
• Supporting actions: Refresh the room list; leave the current room.
• Domain entities: Room (code, mode/map, host, player count, membership), Player identity.
• Component responsibilities:
  • Label-wall grid of tag-chip room cards: each a rectangular label with a punched-hole graphic, room code in uppercase monospace-style tracking, and player count as a ruled table row — no soft cards.
  • Create-room control opening mode/map selection before the room is created.
  • Current-membership banner with a leave action.
  • Hazard-stripe seam between the header and the grid.
• States:
  • Loading: skeleton tag-chips in the grid while the room list is fetched.
  • Empty: a ruled empty state explaining that no rooms are open yet, with the create-room control promoted.
  • Success: grid populates; joining a room routes the player to Play with that room's session.
  • Error: if the room list fails to load, an inline retry is offered; if a join fails because the room filled or closed, the card shows the failure and the player stays on Rooms to pick another.
  • Recovery: refresh and retry keep the player on Rooms.

Play

• Information and state: Protected. Full-viewport game frame showing the low-poly jungle, the player's own gorilla, other players in the same room, and a minimal HUD in tag-chip corners showing room code, player count and locomotion state.
• Primary actions: Move with touch locomotion — run and climb; interact with other players in the shared space.
• Supporting actions: Leave the room and return to Rooms.
• Domain entities: Room session, player presence, player position and locomotion state.
• Component responsibilities:
  • Full-viewport game canvas.
  • Touch locomotion controls for running and climbing.
  • HUD tag-chips in the corners for room code, player count and locomotion state.
  • Ticker tape of quoted verbs along the top of the HUD, pausing to a static wrapped row under reduced motion.
  • Leave control.
• States:
  • Loading: game frame with a loading indicator while the session connects and presence syncs.
  • Empty: if the room has no other players, the HUD shows a player count of one and the world renders normally.
  • Success: the player moves, climbs, and sees other players' positions update in the shared session.
  • Error: if the session connection drops, an inline reconnect notice appears with a retry; if the room closes, the player is returned to Rooms with a notice.
  • Recovery: reconnect restores presence in the same room where possible; otherwise the player returns to Rooms to rejoin.

3. Functional Requirements

FR-1 — Mobile Gorilla Tag-style game. As a Mobile Player, I should play a Gorilla Tag-style movement game on my phone, so that I get the tag-you're-it playground experience on a device I already carry. Provenance: explicit. Trigger: the player opens the app. Observable result: the game renders and is playable in a mobile browser. Access: Landing is anonymous; Play requires login. Failure/recovery: if the device or browser cannot render the game frame, the player sees an inline notice and can return to Landing. Continuation: the player proceeds to identity establishment and room selection.

FR-2 — Touch-based locomotion including running and climbing. As a Mobile Player, I should move through the world using touch-based locomotion including running and climbing, so that movement feels physical on a touchscreen. Provenance: explicit. Trigger: the player touches the locomotion controls on Play. Observable result: the player's gorilla runs and climbs, and the locomotion state is reflected in the HUD. Access: login required (Play). Failure/recovery: if a touch input is not registered, the control remains responsive and the player can retry the gesture. Continuation: the player keeps moving and climbing through the shared world.

FR-3 — Shared multiplayer rooms with visible players. As a Mobile Player, I should join shared multiplayer rooms and see other players in the same session, so that the game feels social and alive. Provenance: explicit. Trigger: the player joins a room from Rooms. Observable result: the player's gorilla and every other player's gorilla appear in the same session, with presence and positions kept in sync. Access: login required (Rooms and Play). Failure/recovery: if presence sync drops, a reconnect notice appears and the player can retry; if the room closes, the player returns to Rooms with a notice. Continuation: the player continues playing in the shared session or picks another room.

FR-4 — Create or join a room. As a Room Host, I should create a room to play with others, and as a Mobile Player I should join an existing room, so that players can gather in the same session. Provenance: explicit. Trigger: the player selects create-room and chooses a mode or map, or selects an existing room card and joins. Observable result: a new room appears in the room list with its code, mode and player count, or the player enters the selected room. Access: login required (Rooms). Failure/recovery: if creation fails, the player stays on Rooms with an inline error and can retry; if a join fails because the room filled or closed, the card shows the failure and the player picks another. Continuation: the host's room becomes joinable by others; the joining player lands on Play.

FR-5 — Self-service enrollment. As a new player, I should enroll on the Login page before entering protected play and room state, so that my in-game identity and room membership are mine. Provenance: required_inference. Trigger: the player chooses enroll on Login and submits a display name and credentials. Observable result: a player identity is created and a session is established. Access: Login is anonymous. Failure/recovery: a duplicate display name or invalid input shows an inline error and preserves the entered values. Continuation: the player is routed to Rooms.

FR-6 — Returning verification. As a returning player, I should verify on the Login page for subsequent sessions, so that I resume my identity and room state. Provenance: required_inference. Trigger: the player chooses verify on Login and submits credentials. Observable result: the existing identity is verified and the session is restored. Access: Login is anonymous. Failure/recovery: invalid credentials show an inline error and preserve the entered values. Continuation: the player is routed to Rooms, or back to the destination they were heading toward.

FR-7 — Redis-backed multiplayer session service. As the system, I should maintain room state and presence in Redis through the backend multiplayer session service, so that players in the same room share presence. Provenance: required_inference. Trigger: a player joins, moves within, or leaves a room. Observable result: room membership, player count and positions are consistent for every player in that room. Access: internal to the backend; no direct human interaction. Failure/recovery: if Redis is unavailable, the backend reports a session error to the affected Play session, which shows a reconnect notice. Continuation: once Redis is reachable again, presence resyncs for the room.

4. User Personas

Mobile Player

The Mobile Player is the core participant: someone on a phone who wants a Gorilla Tag-style movement game they can drop into. Their product context is the Play surface and the Rooms list — they arrive already knowing they want to move, climb and be around other players. Their primary goal is a smooth, playable mobile session with locomotion and multiplayer presence.

Their distinct responsibilities are joining a session, moving and climbing using touch controls, and interacting with other players in the shared space. Their relevant inputs and decisions are which room to join, when to run versus climb, and when to leave a room. They interact with the Room Host as the person whose room they enter, and with other Mobile Players as the gorillas they see and move alongside. Their observable success is a session where their gorilla runs and climbs responsively and other players are visibly present in the same world.

What makes this role different from the Room Host is that the Mobile Player's work is the movement loop itself — the moment-to-moment touch locomotion and shared presence — rather than the act of starting a session for others.

Room Host

The Room Host is a Mobile Player who takes on the responsibility of starting a play session for others. Their product context is the Rooms surface, specifically the create-room flow and the resulting room card. Their primary goal is a populated, running room that others can enter.

Their distinct responsibilities are creating a room, choosing a mode or map, and letting friends join. Their relevant inputs and decisions are the mode or map selection at creation and whether to leave the room once it is running. They interact with Mobile Players as the people who join their room, and they see their room's player count rise as others enter. Their observable success is a room that appears in the room list with its code and mode, and that fills with other players.

What makes this role different from the Mobile Player is the act of creation and ownership of a session — the Room Host's success is measured by whether others can and do enter the room they started, not only by their own movement in it.

5. Core User Flows

Flow A — A new player discovers the game and enrolls

1. The Mobile Player opens the app anonymously and lands on Landing. The concrete hero band shows the quoted GORILLA TAG wordmark with MOBILE in a tag chip, the hazard-stripe band, and the phone mockup showing the low-poly jungle with a gorilla mid-climb.
2. The player reads the ticker of quoted verbs (RUN CLIMB TAG JOIN) and understands the game is touch-locomotion and multiplayer.
3. The player taps JOIN A ROOM. Because no session exists, the app routes to Login.
4. On Login, the player selects enroll, enters a display name and credentials, and submits.
5. The backend creates the player identity and establishes a session. Observable result: the player is routed to Rooms with their identity established.
6. Failure/recovery: if the display name is taken or input is invalid, Login shows an inline error and keeps the entered values; the player corrects and resubmits.
7. Continuation: the player proceeds to Flow C to join a room.

Flow B — A returning player verifies and resumes

1. The Mobile Player opens the app and lands on Landing.
2. The player taps into Login and selects verify.
3. The player submits their credentials.
4. The backend verifies the identity and restores the session. Observable result: the player is routed to Rooms, or back to the destination they were heading toward.
5. Failure/recovery: invalid credentials show an inline error and preserve the entered values; the player retries or switches to enroll.
6. Continuation: the player proceeds to Flow C or Flow D.

Flow C — A Mobile Player joins an existing room and plays

1. The Mobile Player is on Rooms with a verified session. The label-wall grid shows tag-chip room cards with room code, player count and mode.
2. The player scans the grid and selects a room card.
3. The player taps join. The backend adds the player to the room's session in Redis and updates presence.
4. Observable result: the player lands on Play, the full-viewport game frame renders, and the HUD tag-chips show the room code and player count.
5. The player uses touch locomotion to run and climb; the HUD reflects the locomotion state, and other players' gorillas are visible and moving in the same session.
6. Failure/recovery: if the room filled or closed before the join completed, the card shows the failure and the player stays on Rooms to pick another. If the session connection drops during play, a reconnect notice appears with a retry; if the room closes, the player returns to Rooms with a notice.
7. Continuation: the player leaves the room via the leave control and returns to Rooms, or continues playing.

Flow D — A Room Host creates a room and others join

1. The Room Host is on Rooms with a verified session.
2. The host selects create-room and chooses a mode or map.
3. The host confirms. The backend creates the room and records it in MariaDB, with live state in Redis. Observable result: the new room appears in the room list with its code, mode and a player count of one.
4. The host enters the room on Play and begins moving with touch locomotion.
5. A Mobile Player on Rooms sees the host's room card, joins it, and lands on Play in the same session. Observable result: the host sees the player count rise and the new player's gorilla appear in the shared world.
6. Failure/recovery: if creation fails, the host stays on Rooms with an inline error and can retry. If the host leaves, the room closes and any players in it return to Rooms with a notice.
7. Continuation: the host continues playing in the populated room, or leaves and creates another.

6. Visuals Colors and Theme

Muse and headline: Virgil Abloh — Remixed familiarity: a mobile jungle tagged in safety orange.

Mode: Light.

Colour tokens (exact):

No gradients, no glass. Contrast: ink on concrete ≈ 17:1; orange on ink and ink on orange both ≥ 4.5:1 at body size.

Typography:

• Headings: Archivo Black, all-caps, tight tracking (-0.02em), set enormous and flush-left. Key words wrapped in literal quotation marks ('RUN', 'CLIMB', 'TAG').
• Body: Space Grotesk 400/500, with 0.08em letterspacing on uppercase micro-labels and tag-like metadata.
• Scale: 1.5 modular display rhythm — hero wordmark clamp(64px, 12vw, 168px); body ladder 40/28/20/16/14; micro-labels 11px uppercase at 0.12em tracking.
• Inter, Roboto and system fonts are forbidden anywhere.

Shape language: Hard corners everywhere (0px radius on panels and buttons), 2px black borders, exposed 1px grid lines drawn across sections, hazard-stripe bands (repeating 45° orange/yellow) as section dividers and button underlines. Small rectangular garment-tag chips with a punched-hole graphic. Buttons are solid black or solid orange rectangles with an offset 3px shadow — never rounded pills.

Layout: Asymmetric editorial grid with a visible 12-column baseline: oversized headline spanning 9 columns, a narrow right rail of quoted metadata, full-bleed concrete bands between sections. Rooms uses a label-wall grid of tag-chips with room code, player count and mode in ruled table rows. Play is a full-viewport game frame with a minimal HUD in tag-chip corners. Everything stacks cleanly at 375px with the rail dropping below the headline.

Imagery: Product-on-concrete — the mobile game frame rendered against raw grey concrete and chain-link, with low-poly gorilla silhouettes and climbing holds. Industrial textures: scuffed paint, tape, stencilled numbers. No stock people, no gradient blobs, no glossy 3D primitives.

Readability rule: headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px and 1280px, wrapping or scaling to fit, with nothing covering them. Imagery and decoration may crop, bleed, rotate or overlap as the direction asks, as long as they cover no readable text or control.

7. Signature Design Concept

The public entry is a full-bleed concrete band occupying the top 70vh, built as a construction-drawing poster for a tag game.

• Left 9 columns: the wordmark GORILLA TAG in Archivo Black at clamp(64px, 12vw, 168px), stacked on two lines, flush-left, with MOBILE as a small quoted label tucked under the baseline inside a black punched garment-tag chip.
• Beneath the headline: a hazard-stripe band running the full viewport width — repeating 45° orange/yellow construction tape.
• Right side: a single dramatic device mockup — a phone held edge-on at a slight angle, screen showing the low-poly jungle with a gorilla silhouette mid-climb, bleeding off the right edge and partially cropped by the viewport.
• Bottom-left of the band: the primary CTA JOIN A ROOM as a solid orange rectangle, with CREATE ROOM as a black outline button beside it.
• Across the seams: exposed 1px black grid lines at column boundaries, visible behind the headline and content, and a thin ticker of quoted verbs (RUN CLIMB TAG JOIN separated by asterisks) scrolling along the section seam.

No centred headline, no subtext paragraph, no blue button, no gradient. The concept recomposes only accepted Landing content and controls — the two CTAs and the path into Login.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the oversized quoted GORILLA TAG wordmark and the edge-on phone mockup showing a gorilla mid-climb against concrete.
• Input → transformation → outcome thesis: as the page settles, the hazard-stripe band beneath the headline slides one step and the ticker of quoted verbs begins its linear scroll; the phone mockup holds its angle while the wordmark stays fixed. The outcome is a composed, mechanical first frame that reads as a construction poster, not an animated splash.
• Motion vocabulary: snappy and mechanical — 120–180ms linear reveals, ticker tape of quoted words scrolling along section seams, tag-flip on hover (card rotates 2° and swaps its label to a quoted variant), hazard stripes that slide one step on state change. No bounces, no easing theatrics.
• Composed first frame: concrete band, two-line wordmark flush-left, MOBILE tag chip under the baseline, hazard-stripe band beneath, phone mockup bleeding off the right edge, orange JOIN A ROOM and black outline CREATE ROOM pinned bottom-left, ticker at the seam.
• Reduced-motion state: the ticker becomes a static wrapped row of quoted verbs, hover swaps resolve instantly, and the hazard-stripe slide is omitted; the first frame is otherwise identical and fully readable.

9. Non-Functional Requirements

• Mobile playability (explicit): the game must be playable on mobile devices. Touch locomotion must respond to touch input, and the layout must remain usable at 375px, 768px and 1280px without readable text or controls being cropped or covered.
• Multiplayer consistency (required_inference): room membership, player count and presence must be consistent for every player in the same room; Redis is the source of live room state so that presence is shared rather than per-device.
• Durable identity (required_inference): player identity and room records persist in MariaDB so that a returning player can verify and resume, and so that a created room has a durable record.
• Access control (required_inference): Landing and Login are anonymously reachable; Rooms and Play require an established session. There is no differentiated permission model beyond this.
• Visual accessibility (direction): ink on concrete ≈ 17:1; orange on ink and ink on orange ≥ 4.5:1 at body size; hazard yellow is never used as text on light ground.
• Reduced motion (direction): under prefers-reduced-motion, the ticker becomes a static wrapped row and hover swaps resolve instantly.
• No third-party branding (reference directive): no Gorilla Tag assets, branding, names or copy are used; the reference is style and domain only.

10. Tech Stack

• Frontend: React application UI, rendering the four pages (Landing, Login, Play, Rooms) and the touch locomotion game frame.
• Backend: shared FastAPI process for application APIs and domain modules, including the multiplayer session service that reads and writes room state and presence.
• Database: MariaDB for application-owned persistent data — player identity and durable room records.
• Cache/state: Redis for live room state and presence, so that players in the same room share presence.
• Orchestration: docker-compose with the four services — frontend, backend, database (MariaDB) and redis.

11. Assumptions and Constraints

• Assumption (narrow): the game runs in a mobile browser as a first-party web application; no native app store packaging is in scope for this delivery.
• Assumption (narrow): a single shared backend process serves all game APIs; the multiplayer session service is a module within it, not a separate service.
• Constraint (explicit): the game must be playable on mobile devices.
• Constraint (explicit): the Gorilla Tag reference is inspiration only — no assets or branding are copied.
• Constraint (direction): the palette, fonts, hard-corner shape language, hazard-stripe seams, tag-chip motifs and exposed grid lines are fixed; the generic indigo/blue-on-white SaaS template is forbidden.
• Constraint (direction): readable text and controls stay whole at 375px, 768px and 1280px; imagery and decoration may crop and bleed instead.
• Out of scope: cosmetics economy, progression system, social feed, voice chat, ranked matchmaking, and any page beyond Landing, Login, Play and Rooms.

12. Glossary

• Gorilla Tag-style: a movement game in the lineage of Gorilla Tag — low-poly jungle, gorilla avatars, running and climbing, shared rooms. Used as a style and domain reference only.
• Touch locomotion: movement through the world using touchscreen input, including running and climbing.
• Room: a shared multiplayer session with a code, a mode or map, a host, and a player count.
• Room code: the uppercase identifier shown on a room's tag-chip card and in the Play HUD.
• Room Host: the player who created a given room. A role within a room, not a privileged account tier.
• Presence: the live record of which players are in a room and where they are, held in Redis and shared across the session.
• Tag chip: a small rectangular garment-tag label with a punched-hole graphic, used for room cards, the MOBILE label and HUD corners.
• Hazard stripe: a repeating 45° orange/yellow construction-tape band used as a section divider and button underline.
• Ticker tape: a thin marquee of quoted verbs (RUN CLIMB TAG JOIN) scrolling along section seams, static and wrapped under reduced motion.