System Requirements Document for option-flow

1. Introduction

option-flow is a trading system built around option flow data. Its purpose is to let traders and analysts see where options activity is concentrating — call flow and put flow — and use that reading to support trading decisions. The product is information design for market participants: dense, fast-moving flow data presented with calm order so a decision can be reached under time pressure.

The audience is two working roles: the Options Trader, who reads flow to find and judge trade setups, and the Flow Analyst, who studies flow to find unusual activity and patterns and records findings that support trade decisions. Both roles work from the same option flow data, and both reach it only after establishing identity.

The product is delivered as a first-party web application with application-owned identity: an anonymous public entry, self-service enrollment, returning-user verification, and a protected option flow workspace with per-event detail.

2. System Overview

2a. Product Interpretation and Delivery Boundary

option-flow is a first-party web application. The application owns its identity: a visitor arrives anonymously at Landing, enrolls through Sign Up, and returning users verify through Login. The option flow workspace and event detail are protected — they are reachable only after identity is established, and the protected state is never available anonymously.

The current delivery covers exactly five destinations: Landing (public entry), Login and Sign Up (identity access), Option Flow (the durable, revisitable flow list), and Flow Event Details (inspection of a single flow event). Option flow data is application-owned and persisted, so a user's flow view is durable and can be revisited across sessions.

Everything beyond viewing and inspecting option flow data — order entry, brokerage connectivity, portfolio or position tracking, alerts, watchlists, and strategy construction — is outside the current delivery. The system informs trading decisions; it does not execute trades.

2b. Source Content Inventory

Not applicable — no reference directive supplies a content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains that option-flow is a trading system based on option flow data, and that call flow and put flow are read together to support trading decisions. No user-specific data is shown.
• Primary actions: Go to Sign Up (enroll); go to Login (returning user).
• Supporting actions: Read the explanatory sections describing what option flow is and how the two roles use it.
• Domain entities: None persisted; presents product explanation only.
• Component responsibilities: Full-viewport dark grid hero with a 96px flush-left Archivo headline across nine columns; a ruled flow strip beneath it showing call blocks in red and put blocks in yellow; a fixed CTA bar at the base carrying the Sign Up and Login entries; a fixed left rail with numbered section codes in small caps; ruled label/value rows for any explanatory figures.
• States: Loading — static content, no data fetch, no skeleton required. Empty — not applicable. Success — page renders fully with both identity entries visible. Error — not applicable to static content; if a navigation target fails, the CTA remains available for retry. Recovery — user can re-select either CTA.

Login

• Information/state: Anonymous access surface for returning users. Collects the credentials that verify an existing identity.
• Primary actions: Submit credentials to verify identity and continue to Option Flow.
• Supporting actions: Navigate to Sign Up if the visitor has no identity yet; return to Landing.
• Domain entities: User identity (email and password credential).
• Component responsibilities: Ruled label/value form rows with 1px hairline rules; flush-left heading; inline field-level error text; submit control in Vignelli red; link to Sign Up.
• States: Loading — submit control shows an in-progress state and is not re-submittable. Empty — fields blank on first render. Success — identity verified, session established, redirect to Option Flow. Error — invalid credentials show an inline message and preserve the entered email; the password field is cleared. Recovery — user corrects and resubmits, or switches to Sign Up.

Sign Up

• Information/state: Anonymous access surface for a new self-starting trader or analyst. Collects the information needed to create an identity.
• Primary actions: Submit enrollment to create the identity and continue to Option Flow.
• Supporting actions: Navigate to Login if an identity already exists; return to Landing.
• Domain entities: User identity (email and password credential).
• Component responsibilities: Ruled label/value form rows; flush-left heading; inline validation messages per field; submit control in Vignelli red; link to Login.
• States: Loading — submit control shows an in-progress state and is not re-submittable. Empty — fields blank on first render. Success — identity created, session established, redirect to Option Flow. Error — an already-registered email or a rejected field shows an inline message naming the field; entered values other than the password are preserved. Recovery — user corrects and resubmits, or switches to Login.

Option Flow

• Information/state: Protected, durable, revisitable list of option flow events for instruments. Each row presents the instrument, the call/put direction, and the flow values that let a user judge a setup. Rows are ordered so the most decision-relevant flow is readable first.
• Primary actions: Read the flow list; open a single event to inspect it in Flow Event Details.
• Supporting actions: Refresh the list to pick up new flow; scan by direction using the red (call) and yellow (put) colour codes.
• Domain entities: Option flow event (instrument, direction, size, price, timestamp, and the flow values shown per row).
• Component responsibilities: Fixed left rail with numbered section codes; ruled data table with tabular numerals for all prices and sizes; full-width colour bars coding call versus put; 1px hairline row rules; short colour flash on updated rows; row selection leading to Flow Event Details.
• States: Loading — table frame renders with ruled placeholder rows. Empty — a ruled message states that no option flow events are currently available, with a refresh action. Success — rows render with tabular values and direction colour codes. Error — a fetch failure shows an inline ruled error with a retry action while preserving the last successfully loaded rows if any. Recovery — retry re-requests the list; a session that has expired returns the user to Login and back to Option Flow after verification.

Flow Event Details

• Information/state: Protected detail view of one option flow event, showing the full set of values for that event so a user can judge it.
• Primary actions: Read the event's values; return to Option Flow.
• Supporting actions: Move to the adjacent event in the list without returning to the list first.
• Domain entities: Option flow event (the same entity as the list row, in full).
• Component responsibilities: Flush-left heading naming the instrument; ruled label/value rows with tabular numerals; direction colour bar in red or yellow; hairline rules between value groups; back control to Option Flow.
• States: Loading — ruled label/value frame renders with placeholders. Empty — not applicable; an event either exists or does not. Success — all event values render. Error — an unknown or unavailable event shows a ruled message with a return to Option Flow. Recovery — return to the list and re-select the event.

3. Functional Requirements

FR-1 — View option flow data (explicit) As an Options Trader or Flow Analyst, I should view option flow data for instruments so that I can support my trading decisions.

• Trigger/input: the user opens Option Flow after identity is established.
• Observable result: a durable, revisitable list of option flow events renders with instrument, direction, and flow values in ruled rows with tabular numerals.
• Access state: protected — requires verified identity.
• Failure/recovery: a fetch failure shows an inline error with retry and preserves previously loaded rows; an expired session returns the user to Login and back to Option Flow after verification.
• Continuation: the user scans the list and selects an event to inspect.

FR-2 — Inspect a single flow event (explicit) As an Options Trader or Flow Analyst, I should open a single option flow event so that I can examine its full values before deciding.

• Trigger/input: the user selects a row in Option Flow.
• Observable result: Flow Event Details renders the event's complete values in ruled label/value rows with a direction colour bar.
• Access state: protected — requires verified identity.
• Failure/recovery: an unavailable event shows a ruled message with a return to Option Flow.
• Continuation: the user returns to Option Flow or moves to an adjacent event.

FR-3 — Judge a trade setup from flow (explicit) As an Options Trader, I should read call flow and put flow together so that I can find and judge a trade setup.

• Trigger/input: the trader reads the direction colour codes and flow values in Option Flow and Flow Event Details.
• Observable result: call flow is coded red and put flow is coded yellow consistently across list and detail, so direction is readable at a glance.
• Access state: protected.
• Failure/recovery: if values fail to load, the error state names the failure rather than showing stale values as current.
• Continuation: the trader forms a decision outside the system; the system does not execute trades.

FR-4 — Identify unusual activity and patterns (explicit) As a Flow Analyst, I should study option flow to find unusual activity and patterns so that my findings can support trade decisions.

• Trigger/input: the analyst scans the Option Flow list and opens events in Flow Event Details.
• Observable result: the analyst can compare events across the durable list and read each event's full values.
• Access state: protected.
• Failure/recovery: as FR-1 and FR-2.
• Continuation: the analyst records findings outside the system; the system does not store analyst notes.

FR-5 — Self-service enrollment (required_inference) As a new Options Trader or Flow Analyst, I should complete self-service enrollment on Sign Up so that I can reach protected option flow data.

• Trigger/input: the visitor selects Sign Up from Landing and submits the enrollment form.
• Observable result: an application-owned identity is created, a session is established, and the user lands on Option Flow.
• Access state: anonymous entry; the resulting session is verified.
• Failure/recovery: an already-registered email or rejected field shows an inline message naming the field; non-password values are preserved for correction.
• Continuation: the user proceeds to Option Flow.

FR-6 — Returning-user verification (required_inference) As a returning Options Trader or Flow Analyst, I should complete verification on Login so that I can resume my protected option flow work.

• Trigger/input: the visitor selects Login from Landing and submits credentials.
• Observable result: identity is verified, a session is established, and the user lands on Option Flow.
• Access state: anonymous entry; the resulting session is verified.
• Failure/recovery: invalid credentials show an inline message, preserve the email, and clear the password; the user may correct and resubmit or switch to Sign Up.
• Continuation: the user proceeds to Option Flow.

FR-7 — Identity required before protected data (required_inference) As the system, I should require verified identity before any option flow data is shown so that protected data is never exposed anonymously.

• Trigger/input: any request for Option Flow or Flow Event Details without a verified session.
• Observable result: the request is redirected to Login; no flow data is rendered.
• Access state: protected destinations only.
• Failure/recovery: after verification the user is returned to the originally requested destination.
• Continuation: normal protected use.

FR-8 — Durable, revisitable flow list (required_inference) As an Options Trader or Flow Analyst, I should return to Option Flow across sessions and see the current flow list so that my working view is continuous.

• Trigger/input: the user signs in again or refreshes Option Flow.
• Observable result: the list re-renders from persisted option flow data with the same ruled structure and colour coding.
• Access state: protected.
• Failure/recovery: as FR-1.
• Continuation: continued scanning and event inspection.

4. User Personas

Options Trader

• Product context: Works under time pressure reading dense market signals. Needs calm order and instant wayfinding rather than decoration, because a misread direction or value costs money.
• Primary goal: Find and judge a trade setup from option flow.
• Distinct accepted responsibilities: Reads call flow and put flow together in Option Flow, opens individual events in Flow Event Details to confirm the full values, and forms a trading decision. The trader is a consumer of flow, not a recorder of findings.
• Relevant inputs or decisions: Instrument, direction (call versus put), and the flow values per event. The decision — whether a setup is worth taking — is made outside the system.
• Interactions with other accepted participants: Shares the same option flow data with the Flow Analyst; the analyst's recorded findings support the trader's decisions, but that exchange happens outside the system.
• Observable success: The trader can read direction and values at a glance from colour codes and tabular numerals, and can reach a specific event's full detail in one selection.

Flow Analyst

• Product context: Studies option flow to find unusual activity and patterns. Works comparatively across many events rather than on a single setup, so the durable list and consistent row structure matter more than any single detail view.
• Primary goal: Identify unusual activity and patterns in option flow and record findings that support trade decisions.
• Distinct accepted responsibilities: Scans the Option Flow list across sessions, compares events, and opens events in Flow Event Details to read full values. Records findings outside the system.
• Relevant inputs or decisions: Patterns across instruments and directions, and the full values of individual events. The decision — which pattern is worth recording — is the analyst's.
• Interactions with other accepted participants: Supplies findings that support the Options Trader's decisions; both read the same flow data.
• Observable success: The analyst can revisit the flow list across sessions, compare events without losing context, and read every value of an event in full.

5. Core User Flows

Flow A — New user enrolls and reaches option flow (Options Trader or Flow Analyst)

1. The visitor arrives anonymously at Landing and reads the explanation of option flow and the two roles.
2. The visitor selects Sign Up from the fixed CTA bar and lands on Sign Up.
3. The visitor enters an email and password and submits.
4. Sign Up validates the fields. On an already-registered email or a rejected field, an inline message names the field, non-password values are preserved, and the visitor corrects and resubmits.
5. On success, an application-owned identity is created, a session is established, and the user lands on Option Flow.
6. Option Flow renders the durable flow list with ruled rows, tabular numerals, and red call / yellow put colour codes.
7. The user selects an event row and lands on Flow Event Details, which renders the event's full values.
8. The user returns to Option Flow to continue scanning.

Flow B — Returning user verifies and resumes (Options Trader or Flow Analyst)

1. The returning user arrives at Landing and selects Login from the fixed CTA bar.
2. On Login, the user enters email and password and submits.
3. On invalid credentials, an inline message appears, the email is preserved, and the password is cleared; the user corrects and resubmits, or switches to Sign Up.
4. On success, identity is verified, a session is established, and the user lands on Option Flow.
5. Option Flow re-renders the current flow list from persisted data, restoring the user's working view.
6. The user continues scanning or opens an event in Flow Event Details.

Flow C — Trader judges a trade setup (Options Trader)

1. The trader is on Option Flow with a verified session.
2. The trader scans rows, reading direction from the red call and yellow put colour codes and values from tabular numerals.
3. The trader selects a promising event and lands on Flow Event Details.
4. The trader reads the full values in ruled label/value rows and confirms or rejects the setup.
5. The trader returns to Option Flow or moves to an adjacent event to compare.
6. The trader forms a trading decision outside the system; option-flow does not execute trades.

Flow D — Analyst identifies unusual activity and patterns (Flow Analyst)

1. The analyst is on Option Flow with a verified session.
2. The analyst scans the durable list across instruments and directions, comparing events.
3. The analyst opens events in Flow Event Details to read full values and confirm a pattern.
4. The analyst returns to Option Flow and continues comparing.
5. The analyst records findings outside the system to support trade decisions.

Flow E — Protected access is enforced (system, with user recovery)

1. A request for Option Flow or Flow Event Details arrives without a verified session.
2. The system redirects to Login; no flow data is rendered.
3. The user verifies identity on Login.
4. The system returns the user to the originally requested destination.
5. If a session expires mid-use, the user is returned to Login and back to Option Flow after verification; previously loaded rows are not shown as current.

6. Visuals Colors and Theme

Authoritative creative direction: Systematic clarity after Massimo Vignelli. Option flow is information design; the theme is a legible system with a visible grid and coded colours, not decoration.

Mode: Dark.

Colour tokens (exact hex, by role):

Typography: Headings and body both Archivo. Headings in heavy and medium weights, flush left, tight tracking, with one small-caps label style. Modular scale 1.25: 64 / 48 / 32 / 20 / 15 / 13. Tabular numerals for all prices and sizes.

Shape language: Hard edges, 0px radii, 1px hairline rules, full-width colour bars. Colour codes act as wayfinding, not ornament.

Layout: Strict 12-column grid with visible horizontal rules. Label and value pairs align in ruled rows. A fixed left rail holds numbered section codes in small caps.

Imagery: No photography. Diagrams, ruled data tables, and colour-coded flow bars are the image.

Avoid: Rounded cards and soft shadows; gradient fills and glow effects; decorative icons without meaning; centred hero copy; blue primary accents; the generic indigo/blue-on-white SaaS template.

Readability constraint: Headlines, wordmarks, labels, numbers, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit. No other element covers any part of them. Decoration may be cropped or bled off an edge; readable text and controls may not.

7. Signature Design Concept

The public entry is a full-viewport dark grid: a 96px Archivo headline flush left across nine columns, sitting on a visible 12-column grid with red column rules. Beneath it, a live ruled flow strip runs as a transit line — call blocks in Vignelli red, put blocks in yellow — reading as the product's defining state: two directions of flow, side by side, instantly distinguishable. A fixed CTA bar at the base carries Sign Up and Login. A fixed left rail shows numbered section codes in small caps.

The concept recomposes only accepted content: the explanation of option flow, the two identity entries, and the call/put colour coding that the protected workspace uses. It introduces no new behaviour or destination.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: the ruled flow strip — call blocks in red and put blocks in yellow — running beneath the 96px flush-left headline.
• Input → transformation → outcome thesis: the visitor reads the headline and the flow strip as a single composed statement of what option flow is; selecting Sign Up or Login in the fixed CTA bar transforms the anonymous entry into an identity step. No decorative transformation occurs.
• Motion vocabulary: still and instant. Data rows update with a short colour flash only; no decorative animation. The hero itself does not animate.
• Composed first frame: graphite ground, visible 12-column grid with red column rules, 96px Archivo headline flush left across nine columns, ruled flow strip beneath in red and yellow, fixed left rail with numbered section codes, fixed CTA bar at the base.
• Reduced-motion state: identical to the composed first frame — the hero is static by design, so prefers-reduced-motion requires no alternate arrangement. The flow strip is a static ruled composition, not a marquee.

9. Non-Functional Requirements

• Protected data boundary (required_inference): option flow data is never rendered to an unverified session; protected destinations redirect to Login. Rationale: the accepted journey requires identity before viewing protected option flow data.
• Durability (required_inference): option flow data and user identities persist in application-owned storage so the flow list is revisitable across sessions. Rationale: the accepted flow list is described as durable and revisitable.
• Readability under time pressure (explicit, from creative direction): tabular numerals for all prices and sizes; consistent red/yellow direction coding across list and detail; no decorative animation that delays reading.
• Viewport integrity (explicit, from creative direction): readable text and controls remain whole at 375px, 768px, and 1280px.
• Accessibility (basic_default): colour is never the sole carrier of meaning — direction is also stated in text in each row and detail view, so red/yellow coding is reinforced, not relied upon alone.
• Error transparency (required_inference): failed loads are named as failures and never presented as current values.

10. Tech Stack

• Frontend: React application UI.
• Backend: shared FastAPI process for application APIs and domain modules, including identity and option flow endpoints.
• Database: MariaDB for application-owned persistent data — user identities and option flow events.
• Deployment: Docker / docker-compose with the three provisioned services: frontend, backend, database.

11. Assumptions and Constraints

• Assumption (required_inference): option flow data is application-owned and persisted; the system does not depend on a third-party market data provider in the current delivery.
• Assumption (required_inference): identity is email and password based, established self-service through Sign Up.
• Constraint (explicit): the system supports trading decisions by presenting option flow data; it does not execute trades, connect to brokerages, or manage positions.
• Constraint (explicit): no analyst notes, alerts, watchlists, or strategy tools are part of the current delivery; findings are recorded outside the system.
• Constraint (explicit, from creative direction): dark mode only; no rounded cards, soft shadows, gradients, glow effects, decorative icons, centred hero copy, or blue primary accents.
• Constraint (required_inference): no differentiated permissions — both accepted personas see the same option flow data.

12. Glossary

• Option flow — the stream of options activity for instruments, read as call flow and put flow.
• Call flow — options activity on calls; coded Vignelli red (#E8442E).
• Put flow — options activity on puts; coded yellow (#F2C230).
• Flow event — a single recorded instance of option flow for an instrument, with its direction and values; the entity behind an Option Flow row and a Flow Event Details view.
• Instrument — the underlying security an option flow event refers to.
• Trade setup — a potential trade the Options Trader judges from option flow; the decision is made outside the system.
• Unusual activity — option flow that stands out from surrounding activity; what the Flow Analyst looks for.
• Tabular numerals — figures set at equal width so prices and sizes align in ruled columns.