System Requirements Document for car-racing-mumbai

1. Introduction

car-racing-mumbai is a car racing game set on the streets of Mumbai. The player races a car through night-time Mumbai street tracks — the Bandra-Worli Sea Link curve, Marine Drive, and the Gateway of India — and the game must look aesthetic and beautiful, visually attractive enough that people fall for it.

The product intent is a cinematic, luxury-polished street racing experience for young Indian players who want speed, night glamour, and a beautiful Mumbai. The audience is the Street Racer: a player who opens the game, starts a race on a Mumbai street track, drives, and finishes to see the result.

This document is the System Requirements Document requested by Vraj for the car-racing-mumbai project.

2. System Overview

2a. Product Interpretation and Delivery Boundary

car-racing-mumbai is delivered as a first-party web game: a React frontend presents the game surfaces, and a shared FastAPI backend serves the application APIs and domain modules, with MariaDB for application-owned persistent data. All four game surfaces — Landing, Race Start, Race, and Race Result — are application-owned custom pages with no access requirement; the player enters and plays without an account, sign-in, or identity establishment. There is no provider-owned or external-only surface in the current scope.

The current delivery horizon covers the complete playable loop: the player arrives at the Landing page, moves to Race Start to choose a Mumbai street track and begin, drives during the Race, and sees the outcome on Race Result. The aesthetic and beauty constraint applies across every one of these surfaces, not only the entry.

Nothing beyond this loop is current. There is no account system, no multiplayer, no social or sharing feature, no economy, no car customization, and no progression system in the accepted requirements; these are not part of this document's current scope.

2c. Page Content and Component Coverage

Landing

• Information and state: The public entry presents the game's identity — a night-time Mumbai street racing game — and its aesthetic character. Full-bleed dark night scene of Mumbai streets (Bandra-Worli Sea Link curve, Marine Drive, Gateway of India) with wet asphalt, neon reflections, and flowing light trails. Oversized pearl headline sits in the lower left over the dark sky, not over the car. A curved gold hairline traces the road into the distance.
• Primary action: The coral Start Race capsule under the headline, which takes the player to Race Start.
• Supporting actions: None beyond entering the game; the page is the single entry point.
• Domain entities: Game identity, Mumbai street scene imagery, hero race car.
• Component responsibilities: Hero scene layer (WebGL/R3F real-time subject per the creative direction), headline block, Start Race capsule, gold hairline road trace that becomes the page divider on scroll.
• States: Loading — hero scene and imagery load with a dark ground and the headline/Start Race control remaining readable; empty — not applicable (static entry content); success — scene renders and Start Race is available; error/recovery — if the hero scene fails to render, the dark ground, headline, and Start Race capsule remain fully usable so the player can still enter the game.

Race Start

• Information and state: The player selects a Mumbai street track before racing. Track cards are curved capsules with a live mini-map arc and a coral start tab, each presenting a Mumbai street track (Bandra-Worli Sea Link curve, Marine Drive, Gateway of India).
• Primary action: Selecting a track card and confirming the start, which begins the Race on that track.
• Supporting actions: Browsing/selecting among the available track cards; returning to Landing.
• Domain entities: Track (name, Mumbai street location, mini-map arc), selected track.
• Component responsibilities: Curved capsule track cards with mini-map arc and coral start tab, selection state, start confirmation control, back-to-Landing control.
• States: Loading — track cards load against the dark scene; empty — if no track is available, a clear message with a way back to Landing; success — a track is selected and the race starts; error/recovery — if track data fails to load, a readable message and retry/return path keep the player unblocked.

Race

• Information and state: The live race on the selected Mumbai street track. The Race HUD sits in four corner clusters with clear data rows, including a circular speed gauge with a gold arc and coral redline zone. Speed lines stretch on acceleration.
• Primary action: Driving the car along the Mumbai street track.
• Supporting actions: Reading the HUD (speed, race progress) while driving; pausing or exiting the race if the player chooses to stop.
• Domain entities: Car, track, race session, speed, race progress, finish state.
• Component responsibilities: Race scene renderer, four-corner HUD clusters, circular speed gauge with gold arc and coral redline zone, speed-line effect on acceleration, pause/exit control.
• States: Loading — the track scene loads before control is handed to the player; empty — not applicable; success — the player drives and the race reaches its finish, leading to Race Result; error/recovery — if the race cannot start or is interrupted, a readable message offers retry or return to Race Start.

Race Result

• Information and state: The outcome of the completed race on the selected Mumbai street track, presented in the same dark, gold-and-pearl visual language.
• Primary action: Viewing the race result.
• Supporting actions: Racing again (returning to Race Start) or returning to Landing.
• Domain entities: Race result, track, car, finish outcome.
• Component responsibilities: Result presentation panel, race-again control, return-to-Landing control.
• States: Loading — result data resolves; empty — not applicable; success — the result is shown with clear next actions; error/recovery — if the result cannot be resolved, a readable message with race-again and return paths.

3. Functional Requirements

FR-1 — Play a car racing game. As a Street Racer, I should play a car racing game so that I can race cars. (explicit)

• Trigger/input: the player enters the game.
• Observable result: the game is playable as a car racing game.
• Access state: no access requirement.
• Failure/recovery: if the game cannot load, the player sees a readable message and can retry.
• Continuation: the player proceeds into the race loop.

FR-2 — Race on the streets of Mumbai. As a Street Racer, I should race on the streets of Mumbai so that the racing experience is set in Mumbai. (explicit)

• Trigger/input: the player starts a race on a Mumbai street track.
• Observable result: the race takes place on a Mumbai street track (Bandra-Worli Sea Link curve, Marine Drive, Gateway of India).
• Access state: no access requirement.
• Failure/recovery: if a track fails to load, the player can retry or choose another track.
• Continuation: the player drives the selected track.

FR-3 — Experience an aesthetic and beautiful game. As a Street Racer, I should experience a game that looks aesthetic and beautiful so that the game feels visually premium. (explicit)

• Trigger/input: the player views any game surface.
• Observable result: every surface follows the dark night-Mumbai visual language — deep charcoal ground, pearl text, gold hairlines, coral speed accents, curved parametric edges, cinematic motion.
• Access state: no access requirement.
• Failure/recovery: if a visual layer fails, readable text and controls remain whole and usable.
• Continuation: the player continues through the game.

FR-4 — Be drawn in by the game's visual appeal. As a Street Racer, I should find the game visually attractive enough that I fall for it so that I want to keep playing. (explicit)

• Trigger/input: the player first sees the Landing page.
• Observable result: the hero presents a full-bleed night render of a race car sweeping the Bandra-Worli Sea Link curve, an oversized pearl headline, and a coral Start Race capsule.
• Access state: no access requirement.
• Failure/recovery: if the hero scene fails, the headline and Start Race control remain fully readable and usable.
• Continuation: the player starts a race.

FR-5 — Start a race from the Landing page. As a Street Racer, I should open the game and start a race from the Landing page so that I can get into racing immediately. (required_inference)

• Trigger/input: the player activates the Start Race capsule on Landing.
• Observable result: the player arrives at Race Start.
• Access state: no access requirement.
• Failure/recovery: if navigation fails, the Start Race control remains available for retry.
• Continuation: the player selects a track.

FR-6 — Select a Mumbai street track and start. As a Street Racer, I should select a Mumbai street track and start the race so that I race where I choose. (required_inference)

• Trigger/input: the player selects a curved capsule track card and confirms the start.
• Observable result: the Race begins on the selected track.
• Access state: no access requirement.
• Failure/recovery: if track data fails to load, a readable message and retry/return path keep the player unblocked.
• Continuation: the player drives.

FR-7 — Drive the car during the race. As a Street Racer, I should drive the car on the Mumbai street track during the race so that I can compete and finish. (required_inference)

• Trigger/input: the player controls the car during the Race.
• Observable result: the car moves along the track; the HUD shows speed on the circular gauge with gold arc and coral redline zone; speed lines stretch on acceleration.
• Access state: no access requirement.
• Failure/recovery: if the race is interrupted, a readable message offers retry or return to Race Start.
• Continuation: the player reaches the finish.

FR-8 — See the race result. As a Street Racer, I should finish the race and see the race result so that I know the outcome. (required_inference)

• Trigger/input: the player finishes the race.
• Observable result: Race Result presents the outcome with race-again and return-to-Landing actions.
• Access state: no access requirement.
• Failure/recovery: if the result cannot be resolved, a readable message with race-again and return paths.
• Continuation: the player races again or returns to Landing.

4. User Personas

Street Racer

• Product context: A young Indian player drawn to speed, night glamour, and a beautiful Mumbai. They arrive at car-racing-mumbai expecting a cinematic street racing game, not a menu-heavy application.
• Primary goal: Race a car on Mumbai street tracks in a game that looks aesthetic and beautiful enough to fall for.
• Distinct accepted responsibilities: Opens the game at Landing; starts a race from Landing; selects a Mumbai street track at Race Start; drives the car during the Race; finishes and views the Race Result.
• Relevant inputs or decisions: Whether to start a race; which Mumbai street track to select; how to drive the car during the race; whether to race again or return to Landing after the result.
• Interactions with other accepted participants: None — the Street Racer is the only active human persona; no counterparty, recipient, or beneficiary exists in the accepted scope.
• Observable success: The player completes a race on a Mumbai street track and sees the result, having experienced a game that looks aesthetic and beautiful throughout.
• What makes this role different: The role is defined by the act of racing itself — the player is both the audience for the game's beauty and the driver in its race, with no account, no administrative duty, and no other participant to coordinate with.

5. Core User Flows

Flow 1 — Enter the game and start a race (Street Racer)

1. The Street Racer opens car-racing-mumbai and lands on Landing.
2. Landing presents the full-bleed night render of a race car sweeping the Bandra-Worli Sea Link curve, the oversized pearl headline in the lower left over the dark sky, and the gold hairline tracing the road into the distance.
3. The Street Racer reads the headline and activates the coral Start Race capsule beneath it.
4. The player arrives at Race Start.
5. If the hero scene failed to render, the dark ground, headline, and Start Race capsule remain fully readable and the player can still proceed — recovery without leaving the page.

Flow 2 — Select a Mumbai street track and begin (Street Racer)

1. On Race Start, the Street Racer sees curved capsule track cards, each with a live mini-map arc and a coral start tab, representing Mumbai street tracks.
2. The Street Racer selects a track card.
3. The Street Racer confirms the start.
4. The Race begins on the selected Mumbai street track.
5. If track data fails to load, a readable message offers retry or a return to Landing; the player is never left on a blank surface.

Flow 3 — Drive the race (Street Racer)

1. On Race, the Street Racer takes control of the car on the selected Mumbai street track.
2. The four-corner HUD clusters show clear data rows; the circular speed gauge shows a gold arc with a coral redline zone; speed lines stretch on acceleration.
3. The Street Racer drives toward the finish.
4. If the player pauses or exits, a readable control offers resume, retry, or return to Race Start.
5. On reaching the finish, the player moves to Race Result.

Flow 4 — View the result and continue (Street Racer)

1. On Race Result, the Street Racer sees the outcome of the completed race on the selected Mumbai street track.
2. The Street Racer chooses to race again — returning to Race Start — or to return to Landing.
3. If the result cannot be resolved, a readable message offers race-again and return paths so the player can continue.

6. Visuals Colors and Theme

The creative direction — Fluid velocity on Mumbai streets, muse Zaha Hadid — is authoritative for this section.

• Mode: Dark mode throughout.
• Colour tokens by role:
  • Background: #0B0D12 (deep charcoal ground, ~70% of every surface)
  • Surface: #151A24
  • Text: #F4F1EA (pearl white)
  • Primary: #E8B04B (gold — headlines, gauges, hairlines)
  • Accent: #FF4D2E (hot coral — speed, start, and warning only)
  • Muted: #8A93A6
• Typography: Jost throughout. Headings Jost Light 300, wide display caps with open tracking for titles; Jost Medium 500 small caps for labels and data. Modular scale 1.5: 48/72/104/128 display, 28 section, 18 body, 13 label. Display uses clamp(48px, 9vw, 128px).
• Shape language: Long sweeping curves cut section edges; capsule buttons; thin gold hairlines; soft pearl glows. No sharp right angles on primary controls.
• Layout: Full-bleed dark scene on every page; asymmetric curved panels float over the scene; Race HUD in four corner clusters with clear data rows.
• Imagery style: Night renders of Mumbai streets — Bandra-Worli Sea Link, Marine Drive curve, Gateway of India — with wet asphalt, neon reflections, and flowing light trails.
• Readability rule: Headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no element covers any part of them. Imagery and decoration may bleed, crop, or overlap freely.
• Forbidden: Blue or indigo accent on white ground; gradient-blob heroes; identical hover-lift card grids; flat clip-art cars or cartoon characters; bouncy or playful easing; busy text over the car or road surface; the generic indigo/blue-on-white SaaS template.

7. Signature Design Concept

The public entry is a full-bleed night render of a race car sweeping the Bandra-Worli Sea Link curve. A curved gold hairline traces the road into the distance and becomes the page divider on scroll. An oversized pearl headline spans the lower half of the hero over the dark sky — never over the car or road surface — and the coral Start Race capsule sits directly under the headline. Section edges cut as long parametric curves, never straight lines. The composition reads as a single sculptural gesture: the road's curve, the hairline, and the headline share one sweeping line of force, so the first frame already communicates speed and Mumbai night glamour before the player presses Start Race.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: cinematic Hero Dimensionality: webgl

Landing Hero Motion Brief

• Focal subject: The race car sweeping the Bandra-Worli Sea Link curve at night, with the gold hairline tracing the road into the distance.
• Input → transformation → outcome thesis: As the player arrives and moves through the hero, slow camera sweeps and parallax between scene layers reveal the Mumbai night scene; the gold hairline draws along the road and, on scroll, becomes the page divider — the same gesture that leads the eye to the Start Race capsule.
• Motion vocabulary: Slow camera sweeps, parallax between scene layers, speed lines stretching on acceleration, curves morphing on page change. No bouncy or playful easing.
• Composed first frame: Dark sky upper region; the car on the curve mid-frame; the oversized pearl headline in the lower left over the dark sky; the coral Start Race capsule beneath it; the gold hairline arcing from the road toward the headline.
• Reduced-motion state: All motion stops under prefers-reduced-motion; the hero resolves to a static composed frame with the headline, hairline, and Start Race capsule fully readable and usable.

Landing Hero 3D Scene Brief — DIRECTION-DERIVED

A real-time WebGL/R3F scene of the Bandra-Worli Sea Link curve at night: the race car as the crafted hero object on wet asphalt with neon reflections and flowing light trails, a gold hairline curve rendered as a luminous line following the road, and the Mumbai skyline as a layered backdrop. The scene shows the product's defining state — a car at speed on a Mumbai street at night — and hands off to the static composed frame under reduced motion.

9. Non-Functional Requirements

• Aesthetic quality (explicit): The game must look aesthetic and beautiful on every surface, following the dark night-Mumbai visual language in Section 6.
• Visual appeal (explicit): The game must be visually attractive enough that people fall for it; the Landing hero is the primary instrument of that appeal.
• Readability at every viewport (explicit, from the creative direction): Readable text and controls stay whole at 375px, 768px, and 1280px; imagery and decoration may bleed or overlap but never cover readable text or controls.
• Reduced motion (explicit, from the creative direction): All motion stops under prefers-reduced-motion, with a usable static arrangement.
• Performance (required_inference): The Race must render and respond smoothly enough for the player to drive; the WebGL hero must not block the Start Race control from being usable.
• No account requirement (explicit via access contract): All four pages have no access requirement; the game is playable without identity establishment.

10. Tech Stack

• Frontend: React application UI, including the WebGL/R3F hero scene for the Landing page.
• Backend: Shared FastAPI process for application APIs and domain modules (race and track data).
• Database: MariaDB for application-owned persistent data.
• Infrastructure: docker-compose with the backend, database, and frontend services.

11. Assumptions and Constraints

• Assumption: The game is delivered as a browser-based web game via the React frontend and FastAPI backend; no native mobile or console build is specified.
• Assumption: The three Mumbai street tracks named in the creative direction (Bandra-Worli Sea Link curve, Marine Drive, Gateway of India) are the available tracks at Race Start.
• Constraint: The game must look aesthetic and beautiful (explicit).
• Constraint: The game must be visually attractive enough that people fall for it (explicit).
• Constraint: No page requires access establishment; the game is open to play.
• Constraint: The generic indigo/blue-on-white SaaS template is forbidden.

12. Glossary

• Street Racer: The player persona who races cars on Mumbai street tracks.
• Landing: The public entry page presenting the game and the Start Race control.
• Race Start: The page where the player selects a Mumbai street track and begins a race.
• Race: The live driving page with the four-corner HUD and circular speed gauge.
• Race Result: The page presenting the outcome of a completed race.
• Track card: A curved capsule card on Race Start with a live mini-map arc and a coral start tab.
• HUD: The heads-up display in four corner clusters during the Race, including the circular speed gauge with gold arc and coral redline zone.
• Gold hairline: The thin gold curve that traces the road on Landing and becomes the page divider on scroll.