System Requirements Document for precious-metals-dealer

1. Introduction

This document specifies a pricing workbook application for a precious metals dealer. The product's intent is to give a working dealer a single, trustworthy instrument for maintaining a table of precious-metals products whose prices are driven by current spot prices and by premium and related pricing calculations. The dealer maintains product rows, keeps spot prices current, and recalculates prices so that the workbook stays internally consistent and reliable enough to price real metal.

The audience is the professional dealer-operator who runs a pricing desk: someone who values exactness, auditability, and material seriousness, and who needs numbers that mean money rather than a generic admin dashboard.

2. System Overview

The application is a first-party web workbook with application-owned identity. A dealer establishes their own access, then works across a durable product table, a spot-price surface, and a pricing surface that applies premiums and related calculations to produce current prices.

Current delivery consists of seven pages: a public Landing page, two anonymous identity-access pages (Sign Up and Login), and four authenticated working pages (Products, Product Editor, Spot Prices, Pricing). The authenticated pages are protected by login; the Landing, Sign Up, and Login pages are reachable without identity.

Actors:

• Precious Metals Dealer — the sole active human persona; initiates all workbook work.
• Application — owns identity, durable workbook state, spot-price values, and pricing computation.
• Spot-price source — an external provider of current spot prices consumed by the application (non-persona actor).

Narrow exclusions: this document does not add order management, invoicing, customer records, inventory logistics, shipping, tax filing, or multi-role permission structures. No differentiated permissions or role-based visibility are established; the single dealer persona owns all workbook state.

2a. Product Interpretation and Delivery Boundary

The workbook is delivered as a first-party application with application-owned identity. Because the dealer must privately own and resume durable pricing workbook data — product rows, spot prices, and calculated prices — the application establishes identity on first use through self-service enrollment and verifies returning dealers before protected workbook work. No invitation, provisioning, or deployment bootstrap boundary is established by the source.

The anonymous entry surface (Landing) explains the workbook and its capabilities and routes the dealer to enrollment or verification. The protected working surfaces (Products, Product Editor, Spot Prices, Pricing) are unavailable until identity is established; the identity-access surfaces themselves are anonymous because a protected destination cannot own the interaction that establishes access to itself.

Current horizon: product tables, spot-price updating, and premium/related pricing calculations, plus the identity and entry surfaces required to reach them. No future-horizon capabilities are established by the source.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the pricing workbook, its precious-metals-dealer audience, and its product-table, spot-price, and premium-calculation capabilities. Presents the four live spot prices (gold, silver, platinum, palladium) as inline instrument readouts with tabular figures.
• Primary actions: Proceed to Sign Up (begin using the workbook); proceed to Login (return to an existing workbook).
• Supporting actions: Read capability summaries; view live spot readouts.
• Domain entities: Spot price (metal, value), capability summary.
• Component responsibilities: Hero instrument readout; capability sections; primary CTA to enrollment; secondary link to verification.
• States: Loading (spot readouts resolving); empty (spot values unavailable — readouts show an explicit unavailable state, not zero); success (readouts populated); error (spot source unreachable — readouts marked stale/unavailable with a retry affordance); recovery (retry re-requests spot values).

Sign Up

• Information/state: Anonymous enrollment surface. Collects the dealer's identity-establishing information and creates the dealer's workbook ownership.
• Primary actions: Submit enrollment to establish access.
• Supporting actions: Navigate to Login if already enrolled.
• Domain entities: Dealer identity record.
• Component responsibilities: Enrollment form; validation messaging; submit control; link to verification.
• States: Loading (submission in progress); empty (initial form); success (identity established, routed to protected workbook); error (validation failure or enrollment conflict — inline field errors, form preserved); recovery (correct and resubmit).

Login

• Information/state: Anonymous returning-verification surface. Verifies the dealer before protected workbook work.
• Primary actions: Submit credentials to verify identity.
• Supporting actions: Navigate to Sign Up if not yet enrolled.
• Domain entities: Dealer identity record.
• Component responsibilities: Verification form; validation messaging; submit control; link to enrollment.
• States: Loading (verification in progress); empty (initial form); success (verified, routed to protected workbook); error (invalid credentials — non-specific failure message, form preserved); recovery (retry or route to enrollment).

Products

• Information/state: Authenticated durable product table. Lists the dealer's precious-metals product rows with their current prices as driven by spot prices and premiums. Ruled instrument rows with hairline dividers, 11px uppercase column labels, right-aligned tabular numerals.
• Primary actions: Open a product row for editing; create a new product row.
• Supporting actions: Sort/filter the table; navigate to Spot Prices; navigate to Pricing.
• Domain entities: Product (name, metal, weight/unit, premium, current price), spot price reference.
• Component responsibilities: Product table; row actions; create control; spot rail (persistent live spot readouts); empty-state guidance.
• States: Loading (table resolving); empty (no product rows yet — guidance to create the first row); success (rows populated with current prices); error (table load failure — retry affordance); recovery (retry or navigate to Product Editor to re-enter data).

Product Editor

• Information/state: Authenticated create/edit surface for a single product row. Shows the product's fields and the pricing inputs (metal, weight/unit, premium) that feed its calculated price.
• Primary actions: Save the product row (create or update); cancel/discard changes.
• Supporting actions: Delete an existing product row; return to Products.
• Domain entities: Product (name, metal, weight/unit, premium, current price).
• Component responsibilities: Field form; validation messaging; save/cancel controls; delete control for existing rows; spot rail.
• States: Loading (existing row resolving); empty (new-row form); success (row saved, returned to Products with the row reflected); error (validation failure or save failure — inline errors, input preserved); recovery (correct and resave, or discard).

Spot Prices

• Information/state: Authenticated surface for the current spot prices that drive product-table pricing. Shows each metal's current spot value and its recency.
• Primary actions: Update/refresh spot prices.
• Supporting actions: Navigate to Products or Pricing.
• Domain entities: Spot price (metal, value, timestamp/recency).
• Component responsibilities: Spot-price readouts with needles; refresh control; recency indicator; spot rail.
• States: Loading (values resolving); empty (no spot values yet — explicit unavailable state); success (values current); error (source unreachable — stale marking with retry); recovery (retry refresh).

Pricing

• Information/state: Authenticated pricing surface. Applies premiums and related pricing calculations to product rows using current spot prices, producing bid/ask/margin readouts.
• Primary actions: Set a premium and calculate resulting prices; commit recalculated prices to the product table.
• Supporting actions: Select the product row to price; navigate to Products or Spot Prices.
• Domain entities: Product, spot price, premium, calculated price (bid/ask/margin).
• Component responsibilities: Premium dial/control; stacked result readouts; margin-versus-metal-cost split bar; commit control; spot rail.
• States: Loading (spot and product data resolving); empty (no product rows to price — guidance to create one); success (prices calculated and committed, with the affected row pulsed on return to Products); error (missing spot data or invalid premium — explicit message, no commit); recovery (refresh spot prices or correct the premium and recalculate).

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Create the pricing workbook. As a Precious Metals Dealer, I should have a pricing workbook for my business, so that my product pricing lives in one maintained place. (explicit)

• Trigger/input: dealer establishes access and enters the workbook.
• Observable result: a durable workbook owned by the dealer, containing product tables, spot prices, and pricing calculations.
• Access state: protected workbook work requires verified identity.
• Failure/recovery: if identity is not established, the dealer is routed to enrollment or verification.
• Continuation: the dealer proceeds to maintain product rows.

FR-2 — Maintain product tables. As a Precious Metals Dealer, I should maintain product tables of my precious-metals products, so that every product I price has a durable row. (explicit)

• Trigger/input: dealer creates, edits, or deletes a product row.
• Observable result: the product table reflects the added, changed, or removed row.
• Access state: login required.
• Failure/recovery: validation or save failure preserves input and shows inline errors; the dealer corrects and resaves.
• Continuation: the dealer returns to the product table and sees the updated row.

FR-3 — Update product tables by current spot prices. As a Precious Metals Dealer, I should have my product tables updated by current spot prices, so that my prices track the live market. (explicit)

• Trigger/input: current spot prices are available and the dealer refreshes or recalculates.
• Observable result: product-table prices reflect the current spot prices.
• Access state: login required.
• Failure/recovery: if the spot source is unreachable, values are marked stale/unavailable and the dealer can retry; no silent zero substitution.
• Continuation: the dealer continues pricing with current values.

FR-4 — Calculate prices with premiums and related calculations. As a Precious Metals Dealer, I should calculate product prices using premiums and related pricing calculations, so that my bid, ask, and margin reflect my intended premium over metal cost. (explicit)

• Trigger/input: dealer sets a premium and initiates calculation for a product row.
• Observable result: calculated bid/ask/margin figures derived from the current spot price and the premium.
• Access state: login required.
• Failure/recovery: missing spot data or an invalid premium produces an explicit message and no commit; the dealer refreshes spot prices or corrects the premium and recalculates.
• Continuation: the dealer commits the recalculated price to the product table.

FR-5 — Self-service enrollment. As a Precious Metals Dealer, I should be able to establish my own access to the workbook, so that I can begin using it without an invitation or provisioning step. (required_inference)

• Trigger/input: anonymous dealer submits enrollment information.
• Observable result: the dealer's identity is established and their workbook ownership is created.
• Access state: anonymous entry; protected state remains unavailable until identity is established.
• Failure/recovery: validation failure or enrollment conflict shows inline errors and preserves the form.
• Continuation: the dealer is routed into the protected workbook.

FR-6 — Returning verification. As a Precious Metals Dealer, I should verify my identity when returning, so that I can resume control of my durable workbook and pricing data. (required_inference)

• Trigger/input: returning dealer submits verification credentials.
• Observable result: the dealer is verified and regains access to their workbook.
• Access state: anonymous entry; protected destinations remain unavailable until verification succeeds.
• Failure/recovery: invalid credentials produce a non-specific failure message and preserve the form; the dealer retries or routes to enrollment.
• Continuation: the dealer resumes workbook work.

4. User Personas

Precious Metals Dealer

• Product context: A professional dealer-operator running a working pricing desk. They deal in physical precious metals and need a workbook that keeps product pricing aligned with live spot prices and their own premiums. Their relationship to the product is that of an operator to an instrument: they trust it with real money and expect exactness and auditability.
• Primary goal: Maintain an up-to-date, internally consistent pricing workbook — product rows whose prices correctly reflect current spot prices and the dealer's premiums and related calculations.
• Distinct accepted responsibilities: Establishing their own access to the workbook; maintaining the durable product table (creating, editing, deleting product rows); keeping spot prices current; setting premiums and running pricing calculations; committing recalculated prices back to the product table.
• Relevant inputs or decisions: Product identity and metal/weight/unit; the premium to apply; whether to refresh spot prices; whether to commit a recalculated price; whether to correct or discard a failed edit.
• Interactions with other accepted participants: The dealer is the sole active human participant. They interact with the application (which owns identity, durable state, and pricing computation) and indirectly with the external spot-price source whose values the application consumes. No other human participant is affected by the dealer's work.
• Observable success: The product table shows rows whose prices reflect current spot prices and the dealer's premiums; recalculated rows are visibly updated; the workbook remains consistent across revisits.

5. Core User Flows

Journey A — First use: establish access and begin the workbook.

1. The dealer arrives at the anonymous Landing page and reads what the workbook does: product tables, current spot prices, and premium/related pricing calculations. Live spot readouts are visible.
2. The dealer chooses to begin and proceeds to Sign Up.
3. On Sign Up, the dealer enters their enrollment information and submits.
4. The application establishes the dealer's identity and creates their workbook ownership. On success, the dealer is routed into the protected workbook.
5. If enrollment fails validation or conflicts, the form is preserved with inline errors; the dealer corrects the input and resubmits.
6. Continuation: the dealer lands on Products and sees an empty product table with guidance to create the first row.

Journey B — Returning use: verify and resume.

1. The dealer arrives at Landing and chooses to return to their workbook, proceeding to Login.
2. On Login, the dealer submits their verification credentials.
3. The application verifies the dealer and restores access to their durable workbook.
4. If verification fails, a non-specific failure message is shown and the form is preserved; the dealer retries, or routes to Sign Up if not yet enrolled.
5. Continuation: the dealer resumes on Products with their existing rows.

Journey C — Maintain the product table.

1. From Products, the dealer reviews their ruled product rows with current prices.
2. The dealer chooses to create a new product row and opens Product Editor.
3. On Product Editor, the dealer enters the product's fields (name, metal, weight/unit, premium) and saves.
4. The application persists the row. On success, the dealer returns to Products and sees the new row reflected.
5. To change an existing row, the dealer opens it from Products into Product Editor, edits fields, and saves; or deletes the row.
6. If a save fails validation, inline errors appear and the input is preserved; the dealer corrects and resaves, or discards.
7. Continuation: the dealer continues to spot-price and pricing work.

Journey D — Update pricing from current spot prices.

1. From Products (or the persistent spot rail), the dealer navigates to Spot Prices.
2. On Spot Prices, the dealer reviews each metal's current spot value and recency, then refreshes.
3. The application retrieves current spot prices. On success, values and recency update, and product-table pricing reflects the current spot prices.
4. If the spot source is unreachable, values are marked stale/unavailable with a retry affordance — never silently zeroed. The dealer retries.
5. Continuation: the dealer proceeds to Pricing to recalculate.

Journey E — Calculate prices with premiums and commit.

1. From Products or Spot Prices, the dealer navigates to Pricing.
2. On Pricing, the dealer selects the product row to price and sets the premium.
3. The dealer initiates calculation. The application computes bid/ask/margin from the current spot price and the premium, and displays the results with a margin-versus-metal-cost split.
4. If spot data is missing or the premium is invalid, an explicit message appears and no commit occurs; the dealer refreshes spot prices or corrects the premium and recalculates.
5. On a valid result, the dealer commits the recalculated price to the product table.
6. The application persists the recalculated price. On return to Products, the affected row is visibly updated.
7. Continuation: the dealer repeats for other rows or returns to Spot Prices when the market moves.

6. Visuals Colors and Theme

Muse: MARQ by Garmin — luxury instrument aesthetic. Headline direction: Precision instrument, dark titanium, one amber needle.

The workbook reads as a machined instrument: dark, weighted, calibrated, with numbers that mean money. It is a tool trusted with six figures, not a dashboard template.

Color tokens (dark mode):

No blue anywhere. The only permitted gradient is a subtle brushed-metal sheen on gauge bezels.

Typography:

• Headings: Barlow Condensed 600/700, all-caps, +0.02em tracking, for section headers and gauge labels.
• Body: Saira 400; table cells Saira 500.
• Numerals: tabular lining figures mandatory on every price, premium, and percentage so columns align to the decimal.
• Scale: 1.333 modular — 96 / 64 / 40 / 24 / 16 / 13 / 11 px. Micro-labels at 11px uppercase, +0.08em tracking.

Shape language: Machined and circular. Gauges, bezels, and capsule controls with 2px–4px radii (never pill-soft, never fully square); ruled data rows with hairline dividers; a 1px luminous inner edge on active panels; chamfered corners on the primary CTA; topographic contour lines as a section separator motif.

Layout: A dense instrument grid — a fixed 72px left rail of icons with uppercase labels, a top status bar carrying the four live spot prices as inline dials, and a main canvas of ruled, tabular product rows. Left-aligned label/value pairs, right-aligned tabular numerals, 8pt spacing scale, edge-to-edge on data surfaces and generous macro margins on the landing page. Never a grid of identical hover-lift cards — rows and gauges do the work.

Imagery: Macro photography of bullion and coin surfaces on graphite — milled edges, mint marks, brushed and proof finishes, raking light. Topographic contour lines and engraved dial textures as background pattern. Struck-metal brand mark. No stock people, no flat clip art, no gradient blobs.

7. Signature Design Concept

The public Landing page is composed as a desk instrument, not a SaaS splash. A full-bleed dark titanium hero fills the viewport: a single macro bullion bar occupies the right two-thirds, raking amber light across its milled edge, while the left third is a stacked instrument readout. At the top of that readout, LIVE SPOT is set in 11px uppercase amber. Below it, four 96px Barlow Condensed figures — GOLD / SILVER / PLATINUM / PALLADIUM — each sits inside its own thin circular bezel with a needle that sweeps on load. The headline PRICE EVERY OUNCE IN THE ROOM is set in 64px condensed caps, flush left, cut across the seam of the metal image. The primary CTA is a chamfered amber capsule with a 1px inner highlight, reading like a machined button on a bezel. No centred headline, no blue button, no gradient blob. The composition recomposes only accepted content — the workbook's capabilities, the live spot readouts, and the enrollment/verification routes — into a single instrument frame.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: layered_2d

Landing Hero Motion Brief:

• Focal subject: The macro bullion bar with raking amber light, paired with the four circular spot gauges.
• Input → transformation → outcome thesis: On load, the four spot gauges receive their current values; each needle sweeps to its position and each 96px figure counts up over 400ms, resolving into a stable instrument readout that the dealer can read at a glance.
• Motion vocabulary: Needle sweeps on spot-price updates; digits that count up over 400ms; a 1px amber pulse on the row whose price just recalculated; a slow turntable drift on the hero's metal subject. No bounce, no spring, no particle fields; every state change is fast and legible.
• Composed first frame: Dark titanium ground; bullion bar right two-thirds under raking amber light; left third stacked with LIVE SPOT in 11px uppercase amber above four bezelled 96px condensed figures; headline cut across the seam.
• Reduced-motion state: Needles and figures render at their final values immediately; the turntable drift is disabled; the amber pulse is replaced by a static 1px amber row edge.

9. Non-Functional Requirements

• NFR-1 — Numeric precision and alignment. All prices, premiums, and percentages must render with tabular lining figures so columns align to the decimal. (explicit — derived from the authoritative creative direction's typography requirement) Rationale: the dealer reads columns of money figures; misalignment undermines trust.
• NFR-2 — No silent zero substitution. When spot prices are unavailable, the application must mark values stale/unavailable rather than substituting zero. (required_inference) Rationale: a zeroed spot price would produce a plausible but wrong price, which is materially dangerous for a pricing workbook.
• NFR-3 — Durable workbook state. Product rows, spot prices, and calculated prices must persist across sessions and be bound to the correct dealer's identity. (required_inference) Rationale: the dealer must resume and revisit their workbook; the accepted lifecycle requires durable, identity-bound state.
• NFR-4 — Access protection. Products, Product Editor, Spot Prices, and Pricing must be unavailable until identity is established; Landing, Sign Up, and Login must be reachable anonymously. (required_inference) Rationale: a protected destination cannot own the interaction that establishes access to itself.
• NFR-5 — Legible state changes. Every state change (spot update, recalculation, commit) must be fast and legible, with no bounce, spring, or particle effects. (explicit — derived from the authoritative creative direction's motion requirement)
• NFR-6 — No blue accent. No blue or indigo accent may appear anywhere in the interface. (explicit — derived from the authoritative creative direction)

10. Tech Stack

• Frontend: React (web), with the dark titanium instrument theme implemented in CSS.
• Backend: Python / FastAPI, owning identity, durable workbook state, spot-price retrieval, and pricing computation.
• Storage: A relational database for dealer identity, product rows, spot prices, and calculated prices.
• Containerization: Docker / docker-compose for local and deployment packaging.
• Kubernetes: Not required by the source; omitted.

11. Assumptions and Constraints

• A-1: The application owns identity because the dealer must privately own and resume durable workbook data. (required_inference)
• A-2: Enrollment is self-service; no invitation, provisioning, or deployment bootstrap boundary is established by the source. (required_inference)
• A-3: Current spot prices are supplied by an external source consumed by the application; the application does not itself originate market data. (required_inference)
• A-4: The four metals shown in the spot rail are gold, silver, platinum, and palladium, as established by the authoritative creative direction. (explicit — creative direction)
• A-5: No differentiated permissions or role-based visibility exist; the single dealer persona owns all workbook state. (explicit — planning scope)
• A-6: No future-horizon capabilities are established by the source; all requirements are current. (explicit)
• C-1: The generic indigo/blue-on-white SaaS template is forbidden for this project. (explicit — user design constraint)
• C-2: Amber is a signal, not a surface — it must never be used for body text or large fills. (explicit — creative direction)

12. Glossary

• Spot price: The current market price for a precious metal, consumed by the application and used to drive product-table pricing.
• Premium: The dealer-set amount or percentage added over metal cost when calculating a product's price.
• Product table: The dealer's durable table of precious-metals product rows, each with its pricing inputs and current price.
• Product row: A single entry in the product table, describing one product (name, metal, weight/unit, premium, current price).
• Bid / ask / margin: The calculated selling-side, buying-side, and dealer-margin figures produced by the pricing calculation.
• Spot rail: The persistent top-of-app strip of four inline circular gauges with amber needles and tabular price readouts, visible on every authenticated page.
• Workbook: The dealer's complete, identity-bound pricing workspace: product tables, spot prices, and pricing calculations.