System Requirements Document for coral-start

1. Introduction

coral-start is a simple calculator delivered as a single-page design. Its product intent is narrow and complete: a person opens one page, enters numbers and operators, sees the computed result, and can clear the current calculation to start over. There is no second page, no navigation chrome, and no account requirement — the calculator is the whole product.

The audience is anyone who needs quick, accurate basic arithmetic — a daily-use utility that should feel like a sharp, opinionated designed object rather than a form. The interface is anonymous and public: the single Calculator page is the entry point, the working surface, and the result surface at once.

2. System Overview

coral-start is a single-page web calculator. The delivered product consists of exactly one page, Calculator, which is anonymously reachable and hosts all accepted behavior: number and operator entry, the live result display, and clearing the current calculation.

Actors

• Calculator User (human, active): the sole human role. Opens the Calculator page, performs basic arithmetic, reads the result, and clears to start over.
• Frontend application (system): renders the Calculator page, holds the in-progress calculation state, and computes and displays results.
• Shared backend (system): the provisioned FastAPI process for application APIs and domain modules. It supports the application but is not required to own any calculator behavior; arithmetic is performed in the page.
• Database (system): provisioned MariaDB for application-owned persistent data. The accepted calculator behavior creates no durable user-owned state, so no domain entities or persistence are required by this scope.

Delivery shape

• Custom UI: yes — one first-party page.
• Page count: exactly one (explicit constraint: "simple single page design of calculaor").
• Access: none — no identity, sign-in, or session continuity is required or accepted. The calculator is public and ephemeral; each visit starts a fresh calculation.

Accepted behavior summary

1. The product is a simple calculator delivered as a single-page design.
2. Users perform basic arithmetic calculations by entering numbers and operators and viewing the computed result.
3. Users can clear the current calculation to start over.

Narrow exclusions

• No second page, route, or navigation chrome beyond the single calculator.
• No account, sign-in, or saved history.
• No scientific, memory, percentage, or other adjacent calculator functions beyond basic arithmetic entry, result display, and clear.

Removed from scope

• None.

2a. Product Interpretation and Delivery Boundary

coral-start is delivered as one first-party React page served to any visitor. Because the accepted behavior is a public, ephemeral calculation with no durable actor-specific state, commitment, or value transfer, no application-owned identity is introduced: the Calculator page is anonymously reachable and fully usable without sign-in. The shared FastAPI backend and MariaDB database are provisioned infrastructure available to the application; the accepted calculator workflows do not require them to store or compute anything, and this document does not invent domain entities or authentication to justify them.

Everything described in this document is current. No future-horizon requirements are accepted.

2c. Page Content and Component Coverage

Calculator

The single page of the product, anonymously reachable, hosting the full calculator lifecycle.

Information and state

• Display panel: shows the current entry or the computed result as large tabular numerals. Initial state shows 0.
• Expression context: the entered numbers and operators leading to the current display, so the user can see what is being calculated.
• Calculation state: idle (fresh or cleared), entering (digits/operators being composed), and result (a computed value shown).

Primary actions

• Enter digits 0–9 to build the current number.
• Enter operators +, −, ×, ÷ to compose a basic arithmetic expression.
• Press = to compute and display the result.
• Press clear (C/AC) to reset the current calculation to the initial state.

Supporting actions and controls

• Decimal point entry for non-integer operands.
• Backspace/correction of the last entered digit (supporting correction of the current entry).

Domain entities

• Calculation: an in-page, ephemeral expression of operands and operators plus its computed result. Not persisted; discarded on clear or page reload.

Component responsibilities

• Wordmark band: the CALCULATE wordmark in a diagonal mustard band, with the looping operator-word marquee beneath it (static wrapped row under reduced motion).
• Display panel: black block with white numerals, right-aligned; renders the live result and expression context.
• Keypad: 4-column grid of digit keys (white, 2px black rule), operator keys (mustard, black text), a clear key, and an oversized double-height signal-red equals key pinned bottom-right.
• Key press feedback: 90ms snap that collapses the 4px offset shadow.

States

• Loading: not applicable — the page renders its initial 0 state immediately; no data fetch is required.
• Empty: the initial/cleared state showing 0 with no pending expression.
• Success: a computed result displayed in the panel after =.
• Error: invalid input sequences (for example a malformed expression or division by zero) surface a clear, readable error indication in the display panel rather than a silent wrong value; the user recovers by clearing or correcting the entry and continuing.
• Recovery: clear resets to the initial state at any time; correcting the current entry restores a valid expression.

3. Functional Requirements

FR-1 — Single-page calculator delivery (explicit) As a Calculator User, I should get the calculator as a simple single-page design, so that the entire tool is available on one screen without navigation.

• Trigger: opening the product.
• Observable result: exactly one page, the Calculator, renders with the display panel and keypad; no other page or navigation chrome exists.
• Access: anonymous, no sign-in.
• Failure/recovery: not applicable; the page renders its initial state directly.
• Continuation: the user proceeds to enter a calculation.

FR-2 — Enter numbers and operators (explicit) As a Calculator User, I should enter numbers and operators, so that I can compose a basic arithmetic calculation.

• Trigger: pressing digit keys 0–9, the decimal point, and operator keys +, −, ×, ÷.
• Observable result: the display panel and expression context update to show the numbers and operators entered.
• Access: anonymous.
• Failure/recovery: an invalid sequence is indicated in the display; the user corrects the entry or clears.
• Continuation: the user presses = or continues composing.

FR-3 — View the computed result (explicit) As a Calculator User, I should view the computed result of my entered calculation, so that I get the answer I need.

• Trigger: pressing = after a valid expression.
• Observable result: the display panel shows the computed result in large tabular numerals.
• Access: anonymous.
• Failure/recovery: division by zero or a malformed expression shows a readable error in the display; the user clears or corrects and retries.
• Continuation: the user reads the result, then clears or starts a new calculation.

FR-4 — Clear the current calculation (explicit) As a Calculator User, I should clear the current calculation, so that I can start over.

• Trigger: pressing the clear key.
• Observable result: the display resets to the initial 0 state and the pending expression is discarded.
• Access: anonymous.
• Failure/recovery: not applicable; clear always succeeds.
• Continuation: the user begins a new calculation from the initial state.

FR-5 — Correct the current entry (required_inference) As a Calculator User, I should correct the last entered digit, so that a mistyped number does not force a full restart.

• Trigger: pressing backspace while entering.
• Observable result: the last entered digit is removed from the current entry and the display updates.
• Access: anonymous.
• Failure/recovery: backspace on an empty entry leaves the initial state unchanged.
• Continuation: the user continues entering or clears.
• Rationale: indispensable correction mechanic for usable digit entry; introduces no new user goal beyond entering numbers.

4. User Personas

Calculator User

Product context. A person who needs quick, accurate basic arithmetic and opens coral-start's single Calculator page to get it. They arrive anonymously, with no account and no saved state, and expect the tool to be immediately usable.

Primary goal. Compose a basic arithmetic calculation by entering numbers and operators, read the accurate computed result, and clear to start over when done or when correcting a mistake.

Distinct accepted responsibilities.

• Enters digits and operators to build an expression.
• Presses = to compute and reads the result from the display panel.
• Clears the current calculation to reset to the initial state.
• Corrects the current entry when a digit is mistyped.

Relevant inputs and decisions. Which numbers and operators to enter, when the expression is complete enough to evaluate, and whether to clear or correct after a mistake or an error.

Interactions with other participants. The Calculator User is the only human participant. The frontend application renders the page and computes results in response to their input; no other human participant is affected by the calculation.

Observable success. An accurate result appears in the display panel after =; clearing returns the page to 0; the whole interaction happens on one screen with no navigation.

5. Core User Flows

Flow 1 — Perform a basic arithmetic calculation

1. The Calculator User opens coral-start. The single Calculator page renders anonymously with the display panel showing 0 and the keypad visible.
2. The user presses digit keys to enter the first operand; the display panel updates with each digit.
3. The user presses an operator key (+, −, ×, or ÷); the expression context shows the operator and the display is ready for the next operand.
4. The user enters the second operand via digit keys; the display updates.
5. The user presses =. The frontend computes the result and the display panel shows it in large tabular numerals.
6. The user reads the result. To run another calculation, they press clear (Flow 3) or continue entering a new expression.

Failure/recovery. If the user enters a malformed expression or divides by zero, the display panel shows a readable error instead of a wrong value; the user presses clear or corrects the entry and continues.

Flow 2 — Correct a mistyped entry

1. While entering a number on the Calculator page, the user notices a wrong digit in the display.
2. The user presses backspace; the last digit is removed and the display updates.
3. The user continues entering the correct digits, then proceeds with Flow 1 from step 3 or 5.

Failure/recovery. Backspace on an empty entry leaves the initial 0 state unchanged; the user may clear instead.

Flow 3 — Clear and start over

1. On the Calculator page, with a pending expression or a displayed result, the user presses the clear key.
2. The display resets to 0 and the pending expression is discarded.
3. The user begins a new calculation from the initial state (Flow 1, step 2).

6. Visuals Colors and Theme

The creative direction is authoritative: Arithmetic as architecture — the numbers are the poster, after Paula Scher. Typography is structure; colour blocks carry the composition.

Palette (light mode)

The display panel is a solid black block (#111111) with white numerals. Digit keys are white with black text and a 2px black rule; operator keys are mustard with black text.

Typography

• Headings: Anton, uppercase, tight leading (0.9), flush-left and stacked in two or three lines so CALCULATE becomes a colour-block banner.
• Labels and key captions: Oswald medium, uppercase, 0.08em tracking.
• Body: Oswald.
• Scale: 1.333 modular — display clamp(56px, 12vw, 152px); section labels 14px; key captions 20px; result numerals 48px mobile to 88px desktop, tabular.

Shape language. Hard edges only: 0px radius on every key, panel, and colour block. Diagonal bands and offset rectangles. Thick 2px black rules separate display from keypad and keypad from footer. Keys are rectangles with a solid 2px black border and a 4px offset black shadow that collapses on press.

Layout. A single asymmetric editorial column at 1280px: left 60% is the black display panel with the oversized result, right 40% is the keypad in a 4×5 grid. At 768px the display stacks above the keypad; at 375px the display becomes a full-width black band with the result wrapping inside it and the keypad stays a 4-column grid with 56px keys. A full-bleed diagonal mustard band cuts across the top behind the CALCULATE wordmark.

Imagery. Typography is the imagery. A large rotated = glyph in signal red sits behind the keypad as a watermark at 12% opacity. No photography, no illustration — only type, rules, and flat colour fields.

Readability rule. Headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; decoration may bleed and overlap but never covers readable text or controls.

7. Signature Design Concept

The first screen is a full-viewport composition. A mustard diagonal band across the top third holds the black wordmark CALCULATE in Anton at clamp(56px, 12vw, 152px), flush-left, with the band's edge carried by decoration rather than cropping the readable wordmark. Beneath it, the black display panel spans 9 of 12 columns with the live result in white Anton numerals at 88px, right-aligned like a poster caption. The signal-red equals key is oversized — twice the height of a digit key — anchoring the keypad's bottom-right corner. The page ground is warm paper #F4EFE6. No centred headline, no button, no gradient: the result panel and the type band are the hero. A slow operator-word marquee runs along the band beneath the wordmark, and the rotated red = watermark sits behind the keypad at 12% opacity.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the CALCULATE wordmark in the diagonal mustard band and the black display panel with its live white result.
• Input → transformation → outcome thesis: as the user presses keys, the pressed key snaps (90ms, offset shadow collapses), the result numerals flip with a 120ms vertical wipe when they change, and clearing triggers a colour-block wipe — the poster recomposes itself in response to arithmetic.
• Motion vocabulary: slow looping type marquee (CALCULATE • ADD • SUBTRACT • MULTIPLY • DIVIDE) that pauses on hover; 90ms key snap; 120ms vertical wipe on result change; colour-block wipe on clear.
• Composed first frame: mustard diagonal band with the black wordmark and marquee beneath it; black display panel showing 0 in white Anton; keypad with the oversized red equals key at bottom-right; red = watermark behind the keypad.
• Reduced-motion state: the marquee becomes a wrapped static row; result changes crossfade instantly; key presses and clear remain functional without the wipe animations.

9. Non-Functional Requirements

• Single-page constraint (explicit): the product must be a simple single page; no additional pages, routes, or navigation chrome may be introduced.
• Readability across viewports (explicit, from design constraints): readable text and controls remain whole and inside the viewport and their container at 375px, 768px, and 1280px; decoration and motion may bleed or overlap but never cover readable text or controls.
• Reduced motion (explicit, from design constraints): under prefers-reduced-motion, a usable static arrangement is provided — the marquee wraps into a static row and result changes crossfade instantly.
• Anonymous access (required_inference): the Calculator page is reachable and fully usable without identity, because the accepted behavior is public and ephemeral and no durable actor-specific state exists.
• Immediate availability (required_inference): the page renders its initial 0 state without a data fetch, so the calculator is usable on first paint.
• No persistence requirement (required_inference): the accepted calculator behavior creates no durable user-owned state; the provisioned database is not required to store calculation data.

10. Tech Stack

• Frontend: React application UI rendering the single Calculator page, with in-page calculation state and arithmetic evaluation.
• Backend: shared FastAPI process for application APIs and domain modules (provisioned; no calculator-specific API is required by the accepted behavior).
• Database: MariaDB for application-owned persistent data (provisioned; no domain entities are required by this scope).
• Containerization: Docker / docker-compose with the provisioned frontend, backend, and database services.

11. Assumptions and Constraints

• A-1 (explicit): The design must be a simple single page; the page count is exactly one.
• A-2 (explicit): "Basic arithmetic" means the four operations — addition, subtraction, multiplication, division — entered via digit and operator keys with a computed result.
• A-3 (required_inference): The calculator is anonymous and ephemeral; no account, sign-in, or saved history is introduced.
• A-4 (required_inference): Arithmetic is evaluated in the frontend page; the provisioned backend and database support the application but are not required to own calculator behavior.
• A-5 (required_inference): Decimal point entry and backspace correction are supporting mechanics for entering numbers, not separate product goals.
• A-6 (design constraint): The creative direction (Paula Scher-inspired palette, Anton/Oswald typography, hard edges, diagonal bands) is authoritative for visuals and motion; the generic indigo/blue-on-white template is forbidden.

12. Glossary

• Calculator page: the single, anonymously reachable page that is the entire product.
• Display panel: the black block showing the current entry or computed result in white tabular numerals.
• Expression context: the visible numbers and operators leading to the current display.
• Keypad: the 4-column grid of digit, operator, clear, and equals keys.
• Clear: the action that resets the current calculation to the initial 0 state.
• Basic arithmetic: addition, subtraction, multiplication, and division of entered numbers.
• Ephemeral calculation: an in-page calculation that is not persisted and is discarded on clear or reload.