System Requirements Document for agr-r

1. Introduction

agr-r is an agricultural SaaS product built around a single defining artifact: a 3D digital twin of the entire Earth. The product's purpose is to let agricultural decision-makers observe the planet as a living, data-driven model and to see, in three dimensions, how water flows across it — runoff, accumulation, and discharge across terrain and watersheds.

The product intent, derived directly from the authoritative requirement thread, is threefold and non-negotiable:

1. An agricultural-purpose application is built.
2. The application contains a 3D model of the whole Earth — a digital twin.
3. Within that 3D model, the flow of water is visible.

Audience: Agricultural experts and decision-makers — agronomists, land managers, irrigation and watershed planners — who need to read a whole-planet digital twin and watch water move across it in order to ground agricultural planning and intervention decisions. The product is an instrument for serious observation, not a consumer toy.

2. System Overview

agr-r delivers a browser-based, full-bleed 3D Earth twin as its primary surface. The globe is not a decorative render: it is a data sculpture whose arable regions glow, whose hydrology is rendered as luminous fields, and across which animated water-flow ribbons stream, pool in river basins, and discharge at watershed outlets. A thin HUD overlay — a top rail, a left instrument panel of layer toggles, and a right readout column — frames the canvas without competing with it.

Current delivery: A custom first-party web UI (custom_ui: true) with three pages — Landing, 3D Globe, and Water Flow — all reachable without an account (access_requirement: none). There is no application-owned identity, no sign-in, and no account management in the current scope. The product is observational and analytical: the user views the twin, toggles data layers, scrubs scenarios, and reads flow metrics.

Actors:

• Agrár szakértő / döntéshozó (Agricultural expert / decision-maker) — the sole accepted active human persona. This is a closed set of one.
• System processes — the real-time flow simulation, layer re-weighting, and readout computation that run continuously behind the canvas. These are non-persona actors and are never the sole owner of any human-facing capability.

Accepted behavior: Viewing the whole-Earth 3D digital twin; observing 3D water flow across it; toggling data layers (hydrology, arable, elevation, precipitation); switching between named scenarios (baseline / drought / irrigation plan); reading flow metrics (discharge m³/s, runoff coefficient, basin area) that update on hover; and scrubbing the flow simulation along a hairline timeline rail.

Narrow exclusions: No stock photography of fields, tractors, or farmers. No flat 2D map fallback that abandons the digital-twin premise. No account, login, or role/permission system. No transactional, retail, or form-heavy workflows. No future-horizon features are included in current pages or acceptance.

2a. Product Interpretation and Delivery Boundary

agr-r is delivered entirely as a first-party web application. Every accepted capability — the landing presentation, the globe, and the water-flow observation surface — is owned by the application itself and is reachable anonymously. The user does not sign in, does not create an account, and does not resume private durable state; the product is a live instrument that presents the same planetary twin to every visitor. Consequently, no identity establishment, verification, invitation, or provisioning lifecycle exists in the current scope, and none is inferred, because no accepted journey requires durable actor-specific state, a bound commitment, or a value transfer to a specific participant.

The delivery boundary is deliberately narrow. The current product is the twin and the flow: a 3D Earth, its data layers, its animated water, its scenarios, and its readouts. Everything the user does happens on the canvas or in the HUD rails around it. There is no separate data-management, reporting, export, alerting, or collaboration surface in the current scope, and none is added by convention.

Future-horizon material, where it exists, is confined to Section 11 and is excluded from current pages and acceptance.

2c. Page Content and Component Coverage

Landing

• Information / state: A full-viewport, near-black stage (#05070A) holding one large Earth twin, framed slightly off-centre to the right so its terminator line runs diagonally across the screen. Arable regions glow in harvest amber at low intensity; cyan-to-violet flow ribbons stream across continents and pool in river basins, with a soft particle haze trailing the flow. The headline is set into the lower-left third, two lines, ragged right, with a single uppercase micro-label above it and one amber-underlined call to action cut into the dark ground.
• Primary action: Open the twin — enter the 3D Globe working surface.
• Supporting actions: Scroll to scrub the camera and morph the flow field between the three named scenarios (baseline / drought / irrigation plan); read the live coordinate/time readout in the top rail; toggle layers from the thin left rail.
• Domain entities: Earth twin, arable layer, hydrology layer, flow field, scenario (baseline, drought, irrigation plan), coordinate/time readout.
• Component responsibilities:
  • Hero canvas — renders the full-bleed Earth twin and the always-running flow simulation; owns the off-centre composition and the diagonal terminator.
  • Headline block — Space Grotesk headline at clamp(40px, 7vw, 96px), uppercase micro-label "PLANETARY AGRICULTURAL TWIN", amber-underlined CTA "Open the twin"; no button fill, no gradient blob, no centred stack.
  • Top rail (56px) — project mark left, layer toggles centre, live coordinate/time readout right.
  • Left rail of layer toggles — sits 24px from the edge; hydrology, arable, elevation, precipitation as instrument switches.
  • Scroll-scrubbed scenario plates — full-width section plates that slide beneath the fixed canvas as the camera moves; museum-spaced at 120px vertical rhythm, alternating prose and wide data plates, no card grids.
• States:
  • Loading: dark ground with the top rail and micro-label present; the globe resolves as the twin initializes.
  • Empty: not applicable — the twin is always populated with planetary data.
  • Success: the globe renders with arable glow and animated flow ribbons; the CTA is legible and the scroll scrub responds.
  • Error / recovery: if the real-time canvas cannot initialize, the dark ground, headline, micro-label, and CTA remain readable and the user can still proceed to the 3D Globe surface; the flow field is presented as a still frame with a manual play control.
  • Reduced motion: the simulation freezes to a still frame with a manual play control; scroll scrubbing is disabled in favor of direct scenario selection.

3D Globe

• Information / state: The primary working surface — the whole-Earth 3D digital twin at full viewport, with a thin HUD overlay: a 56px top rail (project mark left, layer toggles centre, coordinate/time readout right), a 320px left instrument panel for layer and scenario controls, and a 280px right readout column for flow metrics. The globe rotates on a slow 90s idle orbit. Chrome collapses to icon rails below 1024px while the canvas keeps the full viewport.
• Primary action: Observe and orient the whole-Earth twin — rotate, frame, and read the planet as a data sculpture.
• Supporting actions: Toggle data layers (hydrology, arable, elevation, precipitation) as instrument switches, each flipping on with a 180ms glow and immediately re-weighting the flow field's colour ramp; select a scenario (baseline / drought / irrigation plan); hover any point on the globe to drive the right-hand readout column.
• Domain entities: Earth twin, terrain relief, arable-land layer, hydrology layer, elevation layer, precipitation layer, flow field, scenario, coordinate/time readout, flow metrics (discharge m³/s, runoff coefficient, basin area).
• Component responsibilities:
  • Globe canvas — full-bleed WebGL/R3F Earth twin with topographic relief; the only luminous element alongside the flow field.
  • Top rail (56px) — project mark, layer toggles, coordinate/time readout.
  • Left instrument panel (320px) — layer and scenario controls as thin ruled rails, hairline sliders with a single glowing thumb, and toggle chips that read as small instrument switches, not pills.
  • Right readout column (280px) — tabular Space Grotesk numerals at 28–44px; the single active value rendered in harvest amber.
  • Hairline timeline rail — along the bottom of the canvas; doubles as the scenario switcher.
• States:
  • Loading: dark ground with HUD rails present; the globe resolves progressively as terrain and layers initialize.
  • Empty: not applicable — planetary data is always present.
  • Success: the globe renders with relief, active layers, and the running flow field; readouts respond to hover; layer toggles re-weight the flow ramp.
  • Error / recovery: if a layer fails to load, the globe remains usable with the remaining layers and the failed layer's toggle shows an inactive state; if the canvas fails entirely, the user is returned to the Landing surface with its still-frame fallback.
  • Reduced motion: the idle orbit and flow simulation freeze to a still frame with a manual play control; panel transitions remain at 180ms opacity/translate.

Water Flow

• Information / state: The dedicated water-flow observation surface — the 3D model with the flow field foregrounded. Particle ribbons whose density and hue encode velocity and accumulation stream across continents, pool in valleys, and discharge at watershed outlets. The flow field uses a controlled multi-hue ramp from #38E1C4 through #6FA8FF to #C86BFF so velocity and accumulation are readable as colour, not decoration. A hairline timeline rail runs along the bottom of the canvas.
• Primary action: Observe and interpret the 3D water flow — read where water moves, where it accumulates, and where it discharges.
• Supporting actions: Scrub the flow simulation along the hairline timeline rail; switch scenarios (baseline / drought / irrigation plan) via the same rail; hover any point to read discharge m³/s, runoff coefficient, and basin area in the right readout column; toggle hydrology and precipitation layers to re-weight the flow field.
• Domain entities: Flow field, particle ribbons, velocity, accumulation, watershed outlet, basin, discharge (m³/s), runoff coefficient, basin area, scenario, timeline position.
• Component responsibilities:
  • Flow canvas — full-bleed WebGL/R3F rendering of the persistent particle/ribbon simulation; never stops, only changes density and hue with the selected layer.
  • Hairline timeline rail — scrubber with a single glowing thumb; doubles as the scenario switcher.
  • Right readout column (280px) — discharge m³/s, runoff coefficient, basin area as tabular Space Grotesk numerals; the single active value in harvest amber.
  • Left instrument panel (320px) — hydrology and precipitation layer toggles and scenario controls.
• States:
  • Loading: dark ground with the timeline rail and readout column present; the flow field resolves as the simulation initializes.
  • Empty: not applicable — the flow simulation is persistent.
  • Success: flow ribbons render with velocity/accumulation colour encoding; scrubbing moves the simulation; readouts update on hover; scenario switching morphs the field.
  • Error / recovery: if the simulation cannot run, the flow field is presented as a still frame with a manual play control and the readouts remain available; if the canvas fails entirely, the user is returned to the 3D Globe surface.
  • Reduced motion: the simulation freezes to a still frame with a manual play control; scrubbing remains available as a manual step control.

3. Functional Requirements

Each requirement below is a distinct story point with provenance, lifecycle facts, and observable acceptance. Provenance is explicit where the authoritative thread states it directly, and required_inference where the mechanic is indispensable to make an accepted outcome usable.

FR-1 — Agricultural-purpose application As an agricultural expert / decision-maker, I should use an application built for agricultural purposes, so that my observation work serves agricultural planning and intervention decisions.

• Provenance: explicit.
• Trigger/input: the user opens agr-r.
• Observable result: the product presents itself as an agricultural intelligence instrument — planetary twin, arable layer, hydrology, and flow readouts framed for agronomic meaning.
• Access state: anonymous; no account required.
• Failure/recovery: not applicable at the product level.
• Continuation: the user proceeds to the Landing surface and into the twin.

FR-2 — Whole-Earth 3D digital twin As an agricultural expert / decision-maker, I should view a 3D model of the entire Earth as a digital twin, so that I can read the planet as a single coherent data artifact.

• Provenance: explicit.
• Trigger/input: the user opens the 3D Globe surface.
• Observable result: a full-viewport 3D Earth renders with topographic relief, arable-land and hydrology layers as luminous fields, and a slow 90s idle orbit.
• Access state: anonymous; no account required.
• Failure/recovery: if the canvas cannot initialize, the user is returned to the Landing surface with its still-frame fallback.
• Continuation: the user toggles layers, selects scenarios, and hovers points to read metrics.

FR-3 — Visible 3D water flow As an agricultural expert / decision-maker, I should see the flow of water in 3D within the model, so that I can understand where water moves, accumulates, and discharges.

• Provenance: explicit.
• Trigger/input: the user opens the Water Flow surface or enables the hydrology layer on the 3D Globe.
• Observable result: animated particle/ribbon flow streams across continents, pools in valleys, and discharges at watershed outlets, with density and hue encoding velocity and accumulation on a #38E1C4 → #6FA8FF → #C86BFF ramp.
• Access state: anonymous; no account required.
• Failure/recovery: if the simulation cannot run, the flow field is presented as a still frame with a manual play control.
• Continuation: the user scrubs the timeline, switches scenarios, and reads flow metrics.

FR-4 — Layer toggles as instrument switches As an agricultural expert / decision-maker, I should toggle data layers — hydrology, arable, elevation, precipitation — so that I can re-weight what the twin shows me.

• Provenance: required_inference (indispensable to make the accepted twin and flow observation usable across the named data dimensions in the creative direction).
• Trigger/input: the user flips a toggle in the left instrument panel or left rail.
• Observable result: the layer flips on with a 180ms glow and the flow field's colour ramp immediately re-weights.
• Access state: anonymous; no account required.
• Failure/recovery: if a layer fails to load, the globe remains usable with the remaining layers and the failed toggle shows an inactive state.
• Continuation: the user continues observing with the updated layer set.

FR-5 — Scenario switching As an agricultural expert / decision-maker, I should switch between named scenarios — baseline, drought, irrigation plan — so that I can compare planetary water behavior under different conditions.

• Provenance: required_inference (indispensable to make the accepted flow observation decision-useful across the named scenarios in the creative direction).
• Trigger/input: the user selects a scenario on the hairline timeline rail or in the left instrument panel.
• Observable result: the flow field morphs between scenarios and the readouts update accordingly.
• Access state: anonymous; no account required.
• Failure/recovery: if a scenario fails to load, the previous scenario remains active and the selection is marked unavailable.
• Continuation: the user compares scenarios and continues observing.

FR-6 — Flow metric readouts on hover As an agricultural expert / decision-maker, I should read discharge (m³/s), runoff coefficient, and basin area as I hover any point on the globe, so that I can quantify what I observe.

• Provenance: required_inference (indispensable to make the accepted flow observation interpretable as agronomic data).
• Trigger/input: the user hovers a point on the globe or flow canvas.
• Observable result: the right readout column updates with tabular Space Grotesk numerals at 28–44px, with the single active value rendered in harvest amber.
• Access state: anonymous; no account required.
• Failure/recovery: if a metric is unavailable for a point, the readout shows an unavailable state rather than a fabricated value.
• Continuation: the user moves the cursor and continues reading.

FR-7 — Timeline scrubbing of the flow simulation As an agricultural expert / decision-maker, I should scrub the flow simulation along a hairline timeline rail, so that I can move through the flow's behavior over time.

• Provenance: required_inference (indispensable to make the accepted persistent flow simulation controllable by the user).
• Trigger/input: the user drags the timeline rail's single glowing thumb.
• Observable result: the flow simulation advances or rewinds to the scrubbed position; the rail doubles as the scenario switcher.
• Access state: anonymous; no account required.
• Failure/recovery: if scrubbing is unavailable, the simulation continues from its current position and the rail shows a disabled state.
• Continuation: the user releases the thumb and continues observing.

FR-8 — Landing presentation of the twin As an agricultural expert / decision-maker, I should arrive at a full-height generative hero that presents the Earth twin, so that my first impression is an observatory rather than a landing page.

• Provenance: required_inference (indispensable anonymous entry surface for the accepted twin and flow observation).
• Trigger/input: the user opens agr-r.
• Observable result: a full-viewport near-black stage with the off-centre Earth twin, the headline set into the lower-left third, the micro-label "PLANETARY AGRICULTURAL TWIN", and the amber-underlined CTA "Open the twin".
• Access state: anonymous; no account required.
• Failure/recovery: if the real-time canvas cannot initialize, the dark ground, headline, micro-label, and CTA remain readable and the user can still proceed to the 3D Globe surface.
• Continuation: the user opens the twin or scrolls to scrub the camera and morph the flow field between scenarios.

FR-9 — Scroll-scrubbed camera and scenario morph on Landing As an agricultural expert / decision-maker, I should scroll the Landing page to move the camera and morph the flow field between scenarios, so that the page itself teaches me the twin's behavior.

• Provenance: required_inference (indispensable to make the accepted Landing hero and scenario set usable as a single continuous presentation).
• Trigger/input: the user scrolls the Landing page.
• Observable result: the globe rotates and the flow field morphs between baseline, drought, and irrigation plan as full-width section plates slide beneath the fixed canvas.
• Access state: anonymous; no account required.
• Failure/recovery: under reduced motion, scroll scrubbing is disabled in favor of direct scenario selection.
• Continuation: the user reaches the CTA and opens the twin.

4. User Personas

Agrár szakértő / döntéshozó (Agricultural expert / decision-maker)

Product context. This persona works with planetary-scale agricultural data and needs to read a whole-Earth digital twin as a single coherent artifact. Their work is observational and analytical: they watch water move across terrain, note where it accumulates and discharges, and translate those observations into agricultural planning or intervention decisions. They are not a consumer browsing a map; they are an expert using an instrument, and they expect the data sculpture to be the loud part of the screen while the chrome stays quiet enough for long sessions.

Primary goal. To observe the 3D water flow across the whole-Earth twin and use that observation to ground agricultural planning or intervention decisions.

Distinct accepted responsibilities.

• View the whole-Earth 3D digital twin as a data sculpture with topographic relief, arable-land and hydrology layers.
• Observe the 3D water flow — where it moves, where it accumulates in valleys, and where it discharges at watershed outlets.
• Toggle data layers (hydrology, arable, elevation, precipitation) to re-weight what the twin shows.
• Switch between named scenarios (baseline, drought, irrigation plan) to compare planetary water behavior.
• Read flow metrics — discharge (m³/s), runoff coefficient, basin area — as they hover any point on the globe.
• Scrub the flow simulation along the hairline timeline rail to move through the flow's behavior over time.

Relevant inputs or decisions. The persona decides which layers to enable, which scenario to compare against, which points on the globe to interrogate for metrics, and where in the flow timeline to focus. Their inputs are the layer toggles, the scenario selector, the timeline scrubber, and the cursor position on the globe.

Interactions with other accepted participants. This is the sole accepted active human persona. There is no second human participant, no counterparty, and no recipient whose state changes as a result of this persona's work. The persona interacts only with the system's real-time simulation, layer re-weighting, and readout computation — non-persona system processes that support but never own the human-facing capability.

Observable success. An interpretable 3D water-flow display on the whole-Earth twin, with layer and scenario controls that visibly re-weight the flow field and readouts that quantify what the persona observes — sufficient to support an agricultural planning or intervention decision.

Source-backed constraints. The persona is inferred from the authoritative requirement thread, which asks for an agricultural-purpose digital-twin application in which the whole Earth is visible in 3D and water flow is visible in 3D. No biography, demographics, permissions, or account requirements are asserted, because the source does not establish them.

5. Core User Flows

Flow 1 — Arriving and opening the twin (Agrár szakértő / döntéshozó)

1. The persona opens agr-r and lands on the Landing surface. No account is required; the surface is anonymous.
2. The full-viewport near-black stage presents the Earth twin off-centre to the right, its terminator line running diagonally across the screen. Arable regions glow in harvest amber at low intensity; cyan-to-violet flow ribbons stream across continents and pool in river basins, with a soft particle haze trailing the flow.
3. The persona reads the micro-label "PLANETARY AGRICULTURAL TWIN" and the headline set into the lower-left third, and sees the live coordinate/time readout in the top rail.
4. The persona selects the amber-underlined CTA "Open the twin".
5. Observable result: the 3D Globe surface opens with the whole-Earth twin at full viewport, the HUD rails in place, and the globe rotating on its slow 90s idle orbit.
6. Continuation: the persona proceeds to observe the twin and its layers (Flow 2) or moves to the water-flow surface (Flow 3).

Failure/recovery: if the real-time canvas cannot initialize on Landing, the dark ground, headline, micro-label, and CTA remain readable and the persona can still proceed to the 3D Globe surface; the flow field is presented as a still frame with a manual play control.

Flow 2 — Reading the whole-Earth twin (Agrár szakértő / döntéshozó)

1. The persona is on the 3D Globe surface with the twin rendered at full viewport.
2. The persona flips a layer toggle in the left instrument panel — hydrology, arable, elevation, or precipitation. The toggle reads as a small instrument switch, not a pill.
3. Observable result: the layer flips on with a 180ms glow and the flow field's colour ramp immediately re-weights.
4. The persona hovers a point on the globe.
5. Observable result: the right readout column updates with tabular Space Grotesk numerals — discharge (m³/s), runoff coefficient, basin area — with the single active value rendered in harvest amber.
6. The persona selects a scenario on the hairline timeline rail — baseline, drought, or irrigation plan.
7. Observable result: the flow field morphs between scenarios and the readouts update accordingly.
8. Continuation: the persona continues observing with the updated layer and scenario set, or moves to the water-flow surface (Flow 3).

Failure/recovery: if a layer fails to load, the globe remains usable with the remaining layers and the failed layer's toggle shows an inactive state. If a scenario fails to load, the previous scenario remains active and the selection is marked unavailable. If the canvas fails entirely, the persona is returned to the Landing surface with its still-frame fallback.

Flow 3 — Observing and interpreting 3D water flow (Agrár szakértő / döntéshozó)

1. The persona opens the Water Flow surface, where the flow field is foregrounded on the 3D model.
2. The persona watches the persistent particle/ribbon simulation: ribbons stream across continents, pool in valleys, and discharge at watershed outlets. Density and hue encode velocity and accumulation on the #38E1C4 → #6FA8FF → #C86BFF ramp.
3. The persona drags the hairline timeline rail's single glowing thumb to scrub the simulation.
4. Observable result: the flow simulation advances or rewinds to the scrubbed position; the rail doubles as the scenario switcher.
5. The persona switches scenario on the same rail — baseline, drought, or irrigation plan.
6. Observable result: the flow field morphs between scenarios.
7. The persona hovers a point on the flow canvas.
8. Observable result: the right readout column updates with discharge (m³/s), runoff coefficient, and basin area, with the single active value in harvest amber.
9. Continuation: the persona uses the interpretable flow display to ground an agricultural planning or intervention decision.

Failure/recovery: if the simulation cannot run, the flow field is presented as a still frame with a manual play control and the readouts remain available. If scrubbing is unavailable, the simulation continues from its current position and the rail shows a disabled state. If the canvas fails entirely, the persona is returned to the 3D Globe surface.

Flow 4 — Scroll-scrubbed scenario comparison on Landing (Agrár szakértő / döntéshozó)

1. The persona is on the Landing surface with the fixed full-height canvas.
2. The persona scrolls the page.
3. Observable result: the camera moves — the globe rotates and the flow field morphs between the three named scenarios (baseline / drought / irrigation plan) as full-width section plates slide beneath the fixed canvas at 120px vertical rhythm.
4. The persona reads