System Requirements Document for sage-project

1. Introduction

sage-project is a quantitative analysis instrument for gold prices. It produces a quarter-end study of the gold price on two markets — the global market and the Egyptian market — over the last quarter of the year (الربع الرابع).

The product intent is measurement, not lifestyle: the audience needs figures it can trust, a like-for-like comparison between two markets quoted in different units (global USD per troy ounce, Egyptian EGP per gram), and the calm authority of a precision tool. The analysis is presented as an instrument face — a dial you read, ruled value rows you scan, and charts that draw themselves once — rather than a scrolling dashboard.

The audience is the gold-price analyst (محلل أسعار الذهب): a person whose recurring responsibility is to gather price data for the specified period and present it as a comparative quantitative analysis between the global market and the Egyptian market, and whose success is a clear quantitative analysis covering the last quarter on both levels.

2. System Overview

sage-project is a first-party, browser-delivered analysis surface with three pages:

• Landing — the public entry surface: a full-bleed instrument face that explains the quantitative gold-price analysis for the global and Egyptian markets over the last quarter of the year before the analyses are opened.
• Global Gold — the quantitative analysis of the gold price at the global level during the last quarter of the year.
• Egypt Gold — the quantitative analysis of the gold price at the Egyptian level during the last quarter of the year.

All three pages are owned by the application and are reachable without an access requirement (access_requirement: none). There is no sign-in, no account, and no differentiated permission model: the analyst reads the same published analysis on every visit.

Actors. The only active human actor is the gold-price analyst (محلل أسعار الذهب). Price data for the global market and the Egyptian market is an external input to the analysis; no provider surface is presented to the analyst as a product destination.

Accepted behavior. The system presents, for the last quarter of the year, on each of the two markets: the quarter's headline closing figure with its unit, the quarter's high, the quarter's low, the quarter's average, and the percentage change over the quarter; a ruled price table; decomposition rows; a chart band; and method notes. The two market pages share an identical skeleton so the markets can be read side by side, and the comparison between them is expressed in the same two series colours throughout.

Narrow exclusions. The analysis is bounded to the last quarter of the year and to the two named market levels (global, Egypt). No other period, no other market, and no other instrument is in scope. No blue or indigo accent appears anywhere in the system.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. sage-project is a first-party custom interface delivered in the browser. All three pages are application-owned and publicly readable; the analyst does not create an identity, does not sign in, and does not resume private state. Because no accepted journey requires privately owned or resumable actor-specific state, no commitment bound to a specific participant, and no entitlement or value transfer, application-owned identity is not established and no anonymous pre-identity lifecycle exists as a separate destination. The Landing page is the public entry surface for the analysis itself, not an access boundary.

Current boundary. Current scope is exactly: the quantitative analysis of the gold price at the global level during the last quarter of the year, and the quantitative analysis of the gold price at the Egyptian level during the last quarter of the year, presented through the Landing, Global Gold, and Egypt Gold pages.

Future boundary. Nothing beyond the two market analyses for the last quarter of the year is committed. Any additional period, market, instrument, or analytical dimension is future work and is not part of current pages or acceptance.

2b. Source Content Inventory

Not applicable — no reference directive in this project declares content_source, so no source content inventory is produced.

2c. Page Content and Component Coverage

Landing

• Information / state: the identity of the study (quantitative gold-price analysis, global and Egyptian markets, last quarter of the year); the quarter's headline closing figure with its unit; the quarter's high, low, average, and percentage change; the current market mode (global / Egypt); the period label (الربع الرابع); the last data update; the current unit (USD/oz ↔ EGP/gram).
• Primary action: begin the analysis — the amber-outlined capsule CTA cut into the lower arc of the bezel, which opens the analysis.
• Supporting actions: switch market mode between عالمي and مصر via the physical toggle switches under the dial; switch unit between USD/oz and EGP/gram from the top status strip; move to a numbered section from the instrument rail.
• Domain entities: quarter period, market (global / Egypt), price series, headline close, quarter high, quarter low, quarter average, quarter percentage change, unit of quotation.
• Component responsibilities:
  • Chronograph bezel hero — a full-bleed dark titanium instrument face; an oversized circular bezel (minimum 62vmin) centred slightly right in the RTL grid, ringed with minute ticks and four labelled markers (Q4 open, Q4 high, Q4 low, Q4 close); the quarter's headline figure engraved inside it in 120px condensed tabular numerals with its unit as a small amber capsule badge.
  • Ruled value rows — four engraved data rows around the dial: أعلى سعر، أدنى سعر، متوسط الربع، التغير %; label right, figure left in RTL, hairline rule between, amber tick on the active row.
  • Top status strip — hairline strip carrying 'الربع الرابع' · 'آخر تحديث' · the unit switch.
  • Market mode switches — two physical toggle switches (عالمي / مصر) with an amber needle that slides between them; switching crossfades the dial face in 120ms and swaps the series colour (champagne #D9C18A for global, amber #E8A33D for Egypt).
  • Instrument rail — fixed RTL rail of numbered modes 01 نظرة عامة, 02 السوق العالمي, 03 السوق المصري, 04 المقارنة, with an amber tick and a needle that slides between entries.
  • Contour texture — faint topographic contour lines behind the dial at 4% opacity.
• States:
  • Loading: the dial face renders with its ticks and markers; figures hold at their placeholder position until the quarter data resolves, then count up once.
  • Empty: if no quarter data is available for the selected market, the bezel renders with its ticks and markers but no engraved figure, and the ruled rows show an explicit no-data state rather than a zero.
  • Success: the headline figure, the four ruled rows, and the active market mode are all populated and mutually consistent for the selected market and unit.
  • Error: if the quarter data cannot be read, the dial face and status strip remain, the affected figures are marked unavailable, and the analyst can retry the read or switch market mode.
  • Recovery: retrying re-reads the quarter data and re-runs the count-up once; switching market mode re-renders the dial face for the other market without leaving the page.

Global Gold

• Information / state: the quantitative analysis of the gold price at the global level during the last quarter of the year; the quarter's headline close in USD/oz; quarter open, high, low, average, and percentage change; the ruled price table; decomposition rows; the chart band; method notes; the period label and last data update.
• Primary action: read the global quarter analysis — the headline figure, the ruled price table, the decomposition rows, and the chart band for the global market.
• Supporting actions: switch unit between USD/oz and EGP/gram from the status strip; move between numbered sections from the instrument rail; switch market mode to مصر; open the comparison band.
• Domain entities: global gold price series, USD per troy ounce, quarter open, quarter high, quarter low, quarter close, quarter average, quarter percentage change, decomposition components, method notes.
• Component responsibilities:
  • Hero dial — the same chronograph bezel as the Landing, reading the global quarter's headline close in USD/oz, with the four Q4 markers labelled.
  • Ruled price table — hairline-separated rows of global quarter figures, label right and value left in RTL, amber tick on the active row, never hover-lift cards.
  • Decomposition rows — the global quarter's figures broken into their contributing rows, in the same ruled-row component.
  • Chart band — an area chart of the global USD/oz series for the quarter, drawn left-to-right in 600ms, stroked in champagne #D9C18A.
  • Method notes — the notes describing how the global quarter figures are derived.
  • Top status strip and instrument rail — shared with the Landing skeleton.
• States:
  • Loading: the skeleton renders (dial, ruled rows, chart band frame); the chart stroke draws once when the series resolves.
  • Empty: if the global quarter series is unavailable, the ruled rows and chart band show an explicit no-data state and the method notes remain readable.
  • Success: headline close, open, high, low, average, percentage change, decomposition rows, and the drawn chart are all populated and consistent for the quarter.
  • Error: if the global series cannot be read, the page keeps its skeleton, marks the affected figures unavailable, and offers a retry.
  • Recovery: retry re-reads the global quarter series and re-runs the count-up and the chart draw once; the analyst can continue to the Egyptian page or the comparison band without losing the page.

Egypt Gold

• Information / state: the quantitative analysis of the gold price at the Egyptian level during the last quarter of the year; the quarter's headline close in EGP/gram; quarter open, high, low, average, and percentage change; the ruled price table; decomposition rows; the chart band; method notes; the period label and last data update.
• Primary action: read the Egyptian quarter analysis — the headline figure, the ruled price table, the decomposition rows, and the chart band for the Egyptian market.
• Supporting actions: switch unit between EGP/gram and USD/oz from the status strip; move between numbered sections from the instrument rail; switch market mode to عالمي; open the comparison band.
• Domain entities: Egyptian gold price series, EGP per gram, quarter open, quarter high, quarter low, quarter close, quarter average, quarter percentage change, decomposition components, method notes.
• Component responsibilities:
  • Hero dial — the same chronograph bezel as the Landing and Global Gold, reading the Egyptian quarter's headline close in EGP/gram, with the four Q4 markers labelled.
  • Ruled price table — hairline-separated rows of Egyptian quarter figures, label right and value left in RTL, amber tick on the active row.
  • Decomposition rows — the Egyptian quarter's figures broken into their contributing rows, in the same ruled-row component.
  • Chart band — an area chart of the Egyptian EGP/gram series for the quarter, drawn left-to-right in 600ms, stroked in amber #E8A33D.
  • Method notes — the notes describing how the Egyptian quarter figures are derived.
  • Top status strip and instrument rail — shared with the Landing skeleton.
• States:
  • Loading: the skeleton renders (dial, ruled rows, chart band frame); the chart stroke draws once when the series resolves.
  • Empty: if the Egyptian quarter series is unavailable, the ruled rows and chart band show an explicit no-data state and the method notes remain readable.
  • Success: headline close, open, high, low, average, percentage change, decomposition rows, and the drawn chart are all populated and consistent for the quarter.
  • Error: if the Egyptian series cannot be read, the page keeps its skeleton, marks the affected figures unavailable, and offers a retry.
  • Recovery: retry re-reads the Egyptian quarter series and re-runs the count-up and the chart draw once; the analyst can continue to the global page or the comparison band without losing the page.

3. Functional Requirements

FR-1 — Global quarter analysis (explicit) As محلل أسعار الذهب, I should obtain a quantitative analysis of the gold price at the global level during the last quarter of the year, so that I have a trustworthy reading of the global market for that quarter.

• Trigger/input: the analyst opens the global analysis for the quarter.
• Observable result: the global quarter's headline close in USD/oz, its open, high, low, average, and percentage change, its ruled price table, its decomposition rows, its chart band, and its method notes are presented for the last quarter of the year.
• Access state: publicly readable; no identity required.
• Failure/recovery: if the global quarter series cannot be read, the affected figures are marked unavailable and the analyst can retry.
• Continuation: the analyst can move to the Egyptian analysis or to the comparison band.
• Owner: Global Gold page.

FR-2 — Egypt quarter analysis (explicit) As محلل أسعار الذهب, I should obtain a quantitative analysis of the gold price at the Egyptian level during the last quarter of the year, so that I have a trustworthy reading of the Egyptian market for that quarter.

• Trigger/input: the analyst opens the Egyptian analysis for the quarter.
• Observable result: the Egyptian quarter's headline close in EGP/gram, its open, high, low, average, and percentage change, its ruled price table, its decomposition rows, its chart band, and its method notes are presented for the last quarter of the year.
• Access state: publicly readable; no identity required.
• Failure/recovery: if the Egyptian quarter series cannot be read, the affected figures are marked unavailable and the analyst can retry.
• Continuation: the analyst can move to the global analysis or to the comparison band.
• Owner: Egypt Gold page.

FR-3 — Public entry that explains the study before the analyses (required_inference) As محلل أسعار الذهب, I should land on a public instrument face that explains the quantitative gold-price analysis for the global and Egyptian markets over the last quarter of the year, so that I understand what the study covers before I open either analysis.

• Trigger/input: the analyst arrives at the product.
• Observable result: the Landing instrument face presents the study's identity, the quarter's headline figure with its unit, the quarter's high, low, average, and percentage change, the period label, the last data update, and the unit switch, with a single CTA that begins the analysis.
• Access state: publicly readable; no identity required.
• Failure/recovery: if the quarter data cannot be read, the dial face and status strip remain and the affected figures are marked unavailable, with a retry available.
• Continuation: the analyst begins the analysis and reaches the global or Egyptian analysis.
• Owner: Landing page.

FR-4 — Quarter-bounded scope (explicit) As محلل أسعار الذهب, I should see every figure in the study bounded to the last quarter of the year, so that the analysis answers exactly the period I asked about.

• Trigger/input: any figure, table, decomposition row, or chart is rendered.
• Observable result: the period label reads الربع الرابع and every presented figure belongs to that quarter; no other period is presented as part of the analysis.
• Access state: publicly readable; no identity required.
• Failure/recovery: if a figure cannot be attributed to the quarter, it is not presented as a quarter figure.
• Continuation: the analyst reads the quarter figures on either market page.
• Owner: Landing, Global Gold, and Egypt Gold pages.

FR-5 — Two-market scope (explicit) As محلل أسعار الذهب, I should see the analysis at exactly two market levels — global and Egypt — so that the study covers the two levels I asked about and nothing else.

• Trigger/input: the analyst selects a market mode.
• Observable result: the available market modes are عالمي and مصر; the global market is quoted in USD/oz and the Egyptian market in EGP/gram.
• Access state: publicly readable; no identity required.
• Failure/recovery: if one market's data is unavailable, the other market remains fully readable and the unavailable market is marked as such.
• Continuation: the analyst switches between the two markets without leaving the analysis.
• Owner: Landing, Global Gold, and Egypt Gold pages.

FR-6 — Market mode switching (required_inference) As محلل أسعار الذهب, I should switch between the global and Egyptian markets with a physical mode switch, so that I can move between the two levels of the study without losing my place.

• Trigger/input: the analyst operates the عالمي / مصر toggle.
• Observable result: the amber needle slides to the selected mode, the dial face crossfades in 120ms, and the series colour swaps between champagne #D9C18A (global) and amber #E8A33D (Egypt).
• Access state: publicly readable; no identity required.
• Failure/recovery: if the selected market's data cannot be read, the switch still moves and the target market shows its unavailable state.
• Continuation: the analyst reads the selected market's figures.
• Owner: Landing, Global Gold, and Egypt Gold pages.

FR-7 — Unit switching (required_inference) As محلل أسعار الذهب, I should switch the unit of quotation between USD/oz and EGP/gram from the status strip, so that I can read either market in the unit I need.

• Trigger/input: the analyst operates the unit toggle in the top status strip.
• Observable result: the displayed unit changes and the figures are presented in the selected unit, with the unit shown as a small amber capsule badge beside the headline figure.
• Access state: publicly readable; no identity required.
• Failure/recovery: if a figure cannot be converted to the selected unit, it is marked unavailable rather than shown in the wrong unit.
• Continuation: the analyst continues reading the same market in the selected unit.
• Owner: Landing, Global Gold, and Egypt Gold pages.

FR-8 — Ruled value rows as the primary figure component (required_inference) As محلل أسعار الذهب, I should read every figure as a hairline-separated ruled row with the label right and the value left in RTL, so that prices, spreads, and Egypt/global deltas are all scanned the same way.

• Trigger/input: any figure is presented.
• Observable result: the figure appears as a ruled row with a 1px #2C3237 hairline between rows and an amber tick on the active row; figures are never presented as hover-lift cards.
• Access state: publicly readable; no identity required.
• Failure/recovery: if a row's value is unavailable, the row remains with an explicit unavailable value.
• Continuation: the analyst scans the remaining rows.
• Owner: Landing, Global Gold, and Egypt Gold pages.

FR-9 — Chart band per market (required_inference) As محلل أسعار الذهب, I should see the quarter's price series drawn as an area chart on each market page, so that the quarter's movement is visible as a shape and not only as figures.

• Trigger/input: the market page's series resolves.
• Observable result: an area chart of the quarter's series is drawn left-to-right in 600ms, stroked in champagne #D9C18A for the global market and amber #E8A33D for the Egyptian market.
• Access state: publicly readable; no identity required.
• Failure/recovery: if the series cannot be read, the chart band shows an explicit no-data state and the ruled rows remain readable.
• Continuation: the analyst reads the decomposition rows or moves to the other market.
• Owner: Global Gold and Egypt Gold pages.

FR-10 — Comparison band across the two markets (required_inference) As محلل أسعار الذهب, I should see the global and Egyptian quarter series compared in one band using the same two series colours, so that the two markets can be read against each other.

• Trigger/input: the analyst opens the comparison band.
• Observable result: a dual-axis comparison band presents the global series in champagne #D9C18A and the Egyptian series in amber #E8A33D, with the Egypt/global delta expressed in ruled rows.
• Access state: publicly readable; no identity required.
• Failure/recovery: if either series is unavailable, the band presents the available series and marks the other as unavailable rather than implying a comparison.
• Continuation: the analyst returns to either market page.
• Owner: Landing, Global Gold, and Egypt Gold pages (comparison band within the shared skeleton).

FR-11 — Method notes per market (required_inference) As محلل أسعار الذهب, I should read method notes on each market page, so that I can judge how that market's quarter figures were derived.

• Trigger/input: the analyst reads the method notes section.
• Observable result: the method notes for the market are presented and remain readable even when that market's figures are unavailable.
• Access state: publicly readable; no identity required.
• Failure/recovery: if the notes cannot be read, the section states that they are unavailable.
• Continuation: the analyst returns to the figures.
• Owner: Global Gold and Egypt Gold pages.

FR-12 — Numbered instrument rail navigation (required_inference) As محلل أسعار الذهب, I should navigate the study through a numbered instrument rail (01 نظرة عامة, 02 السوق العالمي, 03 السوق المصري, 04 المقارنة) with a needle that travels to the active section, so that navigation reads like selecting a function on a tool watch.

• Trigger/input: the analyst selects a numbered mode or scrolls the page.
• Observable result: the active mode is marked by an amber tick and the vertical needle travels to it.
• Access state: publicly readable; no identity required.
• Failure/recovery: if a section is unavailable, its rail entry remains and the section shows its unavailable state.
• Continuation: the analyst continues to the next numbered mode.
• Owner: Landing, Global Gold, and Egypt Gold pages.

FR-13 — Counting figures and needle-sweep reveals (required_inference) As محلل أسعار الذهب, I should see each figure count up once on entry and each chart stroke draw once, so that the instrument reads as a live measurement without becoming decorative.

• Trigger/input: a page or section enters view with resolved data.
• Observable result: figures count up once in 300ms with ease-out and no bounce; chart strokes draw left-to-right in 600ms; the needle settles with a single 80ms overshoot then stops; live price ticks flash 1px amber on change.
• Access state: publicly readable; no identity required.
• Failure/recovery: if data resolves after the reveal, the figure counts up once at that point; if the analyst prefers reduced motion, the figures and strokes appear in their final state without the count-up or draw.
• Continuation: the analyst reads the settled figures.
• Owner: Landing, Global Gold, and Egypt Gold pages.

4. User Personas

محلل أسعار الذهب (Gold Price Analyst)

Product context. The analyst performs a quarter-end study of the gold price on two markets at once: the global market, quoted in USD per troy ounce, and the Egyptian market, quoted in EGP per gram. The work is recurring and period-bound — the last quarter of the year — and its output is a comparative quantitative reading rather than a narrative report. The analyst arrives already knowing what a quarter open, high, low, close, average, and percentage change mean, and expects the instrument to present those figures without explaining them.

Primary goal. To obtain a clear quantitative analysis covering the last quarter of the year on both the global and the Egyptian level, with the two markets readable against each other.

Distinct accepted responsibilities.

• Gather the price data for the specified period — the last quarter of the year — for the global market and for the Egyptian market.
• Present that data as a comparative quantitative analysis between the global market and the Egyptian market.
• Read each market's quarter figures: headline close with its unit, open, high, low, average, and percentage change.
• Read each market's ruled price table and decomposition rows.
• Read each market's quarter series as a chart, and read the two markets together in the comparison band.
• Judge how each market's figures were derived from the method notes.

Relevant inputs and decisions.

• Which market to read: عالمي or مصر.
• Which unit to read in: USD/oz or EGP/gram.
• Which numbered section of the study to move to: 01 نظرة عامة, 02 السوق العالمي, 03 السوق المصري, 04 المقارنة.
• Whether the presented quarter figures are trustworthy enough to use, based on the method notes and the last data update.

Interactions with other accepted participants. The analyst is the only active human participant in the product. The global and Egyptian price data are external inputs to the analysis, not counterparties the analyst negotiates with; the analyst's interaction is with the instrument's reading of that data.

Observable success. The analyst has, for the last quarter of the year, a complete and internally consistent set of figures for both markets — headline close with unit, open, high, low, average, percentage change, ruled table, decomposition rows, chart, and method notes — and can read the two markets side by side in the same two series colours.

What makes this role distinct. The analyst's work is measurement under a fixed period and a fixed pair of markets. The role is defined by the obligation to cover both levels for the same quarter and to compare them, not by any account, permission, or administrative function — the analyst holds no differentiated control over shared product state, and the study is publicly readable.

5. Core User Flows

Flow A — Read the global quarter analysis (محلل أسعار الذهب)

1. The analyst arrives at the Landing page. The instrument face renders: the chronograph bezel with its minute ticks and four labelled Q4 markers, the top status strip reading 'الربع الرابع' · 'آخر تحديث' · the unit switch, and the four ruled rows (أعلى سعر، أدنى سعر، متوسط الربع، التغير %).
2. The analyst reads the headline figure engraved inside the bezel — the quarter's closing price — with its unit shown as a small amber capsule badge, and confirms the period is the last quarter of the year.
3. The analyst selects the global market using the عالمي / مصر mode switch. The amber needle slides to عالمي, the dial face crossfades in 120ms, and the series colour becomes champagne #D9C18A.
4. The analyst activates the amber-outlined capsule CTA 'ابدأ التحليل', cut into the lower arc of the bezel, and reaches the Global Gold page.
5. On Global Gold, the analyst reads the hero dial's headline close in USD/oz, then the ruled price table: quarter open, high, low, close, average, and percentage change, each as a