System Requirements Document for video-streaming-ledger

1. Introduction

video-streaming-ledger is a production-ready, global, Netflix-style video streaming platform with an integrated financial core. It combines an immersive HLS.js streaming experience with an immutable double-entry financial ledger, a micro-transactional wallet system, a creator payout dashboard, and an administrative control center. The product's defining idea is that watching is a financial event: a streamer's wallet is charged and a creator's wallet is credited at the moment a watch session crosses the 70% completion milestone, and every balance change is written to an append-only, idempotent ledger that administrators can audit in real time.

The audience is three distinct roles operating on one shared financial system:

• Streamers (Viewers) who fund a wallet via card or mobile money and pay per-stream micro-charges as they watch.
• Creators who earn micro-payouts per qualified view, monitor real-time earnings and view counts, and withdraw balances net of a 40% platform commission.
• Admins who oversee platform finances, executive KPIs, and the immutable ledger.

The platform is delivered as a React/Next.js + Tailwind CSS frontend, a Node.js/Express REST API, a PostgreSQL database holding the ledger, and a docker-compose.yml that spins up PostgreSQL and the Node.js backend container.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The product is a first-party web application. All three accepted human roles — Streamer (Viewer), Creator, and Admin — interact with application-owned surfaces. Identity is application-owned: users self-enroll with a role and return via JWT-based login at POST /v1/auth/login. The Landing, Login, and Sign Up surfaces are anonymously reachable; the Streaming Player View, Wallet, Creator Studio Dashboard, and Admin Control Center are role-restricted and require an authenticated session.

Money movement has two external owners that the application integrates with but does not replace:

• Payment gateways (Stripe and Paystack) own card and mobile money collection. The application creates payment intents via POST /v1/billing/create-intent and credits wallets only after an idempotent webhook confirmation at /webhook/stripe or /webhook/paystack.
• Payout providers (Stripe Connect / Paystack payout APIs) own the dispatch of the 60% net creator payout after the platform has deducted and routed the 40% commission to the platform wallet.

Playback telemetry, milestone settlement, ledger writes, and commission routing are application-owned backend processes. The frontend player tracks watch time (handling seeks and scrubs) and sends a cryptographically signed heartbeat; the backend validates it before any settlement occurs.

The current delivery horizon covers everything described in this document. No future-horizon features are specified by the source.

Removed from scope

• None. The authoritative requirement thread does not remove any previously requested concept.

2b. Source Content Inventory

Not applicable — no reference directive declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the Netflix-style streaming platform, wallet-based per-stream pricing (\xe2\x82\xa660 / ~$0.040 full movie or series;\x20\xe2\x82\xa630 / ~$0.020 season episode), the 70% watch milestone settlement model, and creator earnings with the 40% platform commission on withdrawal.
• Primary actions: Enter Sign Up; enter Login.
• Supporting actions: Read pricing and creator-earnings explanation; view the settlement-rail illustration of watch progress becoming a ledger receipt.
• Domain entities: Pricing tiers (full movie/series, season episode), milestone threshold (70%), commission rate (40%).
• Component responsibilities: Full-viewport graphite control-room hero with a cropped 16:9 streaming frame, oversized "WATCH. SETTLE. CREATE." headline, and a vertical settlement rail showing wallet balance, 70% threshold line, creator credit, and platform fee entries; acid-green playback line cutting from the video frame into the ledger rail; primary CTAs to Sign Up and Login.
• States: Loading (static content, no data fetch required); empty (n/a); success (rendered); error (n/a); recovery (n/a).

Login

• Information/state: Anonymous returning-verification surface. Collects credentials and submits to POST /v1/auth/login; on success issues a JWT and routes the user to the surface appropriate to their role.
• Primary actions: Submit credentials; receive JWT.
• Supporting actions: Navigate to Sign Up.
• Domain entities: User account, role (streamer, creator, admin), JWT.
• Component responsibilities: Credential form; inline validation; error display for invalid credentials; post-login role-based routing.
• States: Loading (submitting); empty (n/a); success (JWT issued, redirect); error (invalid credentials — inline message, form preserved); recovery (retry submission).

Sign Up

• Information/state: Anonymous self-service enrollment. Creates an account with a role of streamer, creator, or admin.
• Primary actions: Submit enrollment with chosen role; receive account and proceed to Login or authenticated session.
• Supporting actions: Navigate to Login.
• Domain entities: User account, role.
• Component responsibilities: Enrollment form with role selection; validation; error display; success handoff to Login.
• States: Loading (submitting); empty (n/a); success (account created); error (validation or duplicate account — inline message, form preserved); recovery (correct and resubmit).

Streaming Player View

• Information/state: Authenticated, role-restricted to Streamer (Viewer). Hosts the HLS.js adaptive-bitrate player, a live navbar wallet balance, watch-time tracking that handles seeks and scrubs, and automatic signed telemetry heartbeats at the 70% milestone. Displays the per-stream charge applicable to the content type.
• Primary actions: Play/pause/seek; watch content; trigger the 70% milestone heartbeat.
• Supporting actions: View live wallet balance in the navbar; navigate to Wallet to fund balance; observe milestone settlement state.
• Domain entities: Video session, content item (full movie/series or season episode), watch-time telemetry, signed heartbeat packet, wallet balance, per-stream charge.
• Component responsibilities: HLS.js player (VideoPlayer.jsx); navbar wallet balance display; watch-time tracker with seek/scrub handling; signed heartbeat emitter; milestone status indicator; insufficient-balance prompt routing to Wallet.
• States: Loading (manifest/stream buffering); empty (no content selected); success (playback active, milestone settled, balance updated); error (stream load failure, telemetry rejection, insufficient balance); recovery (retry stream, retry heartbeat, fund wallet and resume).

Wallet

• Information/state: Authenticated, role-restricted to Streamer (Viewer). Shows live balance_usd (numeric precision 12,4) and the top-up flow with a $3.00 minimum and tiered AOV bundles. Credits are applied only after idempotent webhook confirmation.
• Primary actions: Select a top-up bundle (≥ $3.00); initiate payment via POST /v1/billing/create-intent; complete payment on the gateway.
• Supporting actions: View current balance; view top-up confirmation state.
• Domain entities: Wallet, balance_usd, top-up bundle, payment intent, webhook confirmation, ledger entry.
• Component responsibilities: Balance display; bundle selector enforcing the $3.00 minimum; payment-intent submission; pending-confirmation state; success state after webhook credit; error display for declined or failed payments.
• States: Loading (balance fetch, intent creation); empty (zero balance with top-up prompt); success (webhook-confirmed credit, updated balance); error (below-minimum amount, declined payment, webhook not yet received); recovery (retry intent, wait for confirmation, choose different bundle).

Creator Studio Dashboard

• Information/state: Authenticated, role-restricted to Creator. Displays real-time earnings cards, total views, a live micro-payout activity feed ($0.022 / $0.040 entries), and a Withdrawal Modal that computes the 40% platform fee split live before submission. Data sourced from GET /v1/creator/metrics.
• Primary actions: Request withdrawal via the Withdrawal Modal submitting to POST /v1/creator/withdraw.
• Supporting actions: Review earnings cards, total views, and micro-payout feed; preview the 40% commission and 60% net split in the modal before confirming.
• Domain entities: Creator earnings, view counts, micro-payout entries, withdrawal request, 40% commission, 60% net payout, ledger entries.
• Component responsibilities: Statement-style earnings module with oversized total and ruled rows for qualified views, gross stream value, pending withdrawals, and net payout; live micro-payout feed; Withdrawal Modal with live fee-split calculation; submission and confirmation states.
• States: Loading (metrics fetch); empty (no earnings yet); success (withdrawal submitted, ledger entries logged, confirmation shown); error (metrics fetch failure, withdrawal validation failure, payout dispatch failure); recovery (retry fetch, adjust amount, retry withdrawal).

Admin Control Center

• Information/state: Authenticated, role-restricted to Admin. Displays executive financial KPIs — Total Deposits, Gross Volume, 40% Platform Revenue, Active User Balance Float — and a real-time ledger auditing table. Data sourced from GET /v1/admin/analytics.
• Primary actions: Review KPIs; audit the ledger table.
• Supporting actions: Inspect individual ledger rows (timestamp, idempotency key fragment, debit account, credit account, amount, immutable status); identify tangerine-marked commission entries.
• Domain entities: Total deposits, gross volume, 40% platform commission revenue, active user balance float, ledger transaction (immutable, append-only, idempotency key).
• Component responsibilities: KPI strip with tabular figures; real-time ledger auditing table with fixed tabular columns; commission-entry visual marking; refresh/live-update behavior.
• States: Loading (analytics fetch); empty (no transactions yet); success (KPIs and ledger rendered); error (analytics fetch failure); recovery (retry fetch).

3. Functional Requirements

Identity and Access

FR-1 — Self-service enrollment with role selection (required_inference) As a prospective user, I should create an account by choosing a role of streamer, creator, or admin, so that I can access the surface appropriate to my role.

• Trigger/input: enrollment form submission on Sign Up.
• Observable result: a user account is created with the selected role; the user proceeds to Login or an authenticated session.
• Access state: anonymous.
• Failure/recovery: validation or duplicate-account error is shown inline and the form is preserved for correction.
• Continuation: successful enrollment leads to Login or the role-appropriate authenticated surface.

FR-2 — JWT-based returning login (explicit) As a returning user, I should authenticate at POST /v1/auth/login and receive a JWT, so that I can resume my role-specific work.

• Trigger/input: credentials submitted on Login.
• Observable result: a JWT is issued and the user is routed to the surface for their role.
• Access state: anonymous entry; authenticated session after success.
• Failure/recovery: invalid credentials produce an inline error and the form is preserved for retry.
• Continuation: authenticated session grants access to the role-restricted surfaces.

Wallet Funding

FR-3 — Wallet balance display (explicit) As a Streamer, I should see my live balance_usd (numeric precision 12,4) in the Wallet and in the player navbar, so that I know my available funds before and during playback.

• Trigger/input: authenticated view of Wallet or Streaming Player View.
• Observable result: current balance_usd is displayed.
• Access state: authenticated, role-restricted to Streamer.
• Failure/recovery: balance fetch failure shows an error with retry.
• Continuation: the displayed balance informs top-up and playback decisions.

FR-4 — Top-up with $3.00 minimum and tiered AOV bundles (explicit) As a Streamer, I should fund my wallet via card or mobile money using tiered AOV bundles with a $3.00 minimum, so that I have balance to pay per-stream charges.

• Trigger/input: bundle selection (≥ $3.00) and payment initiation via POST /v1/billing/create-intent.
• Observable result: a payment intent is created and the user completes payment on the gateway.
• Access state: authenticated, role-restricted to Streamer.
• Failure/recovery: amounts below $3.00 are rejected; declined or failed payments show an error and allow retry.
• Continuation: successful payment proceeds to webhook confirmation (FR-5).

FR-5 — Idempotent webhook-confirmed wallet credit (required_inference) As a Streamer, I should have my wallet credited only after the payment gateway confirms via /webhook/stripe or /webhook/paystack, so that my balance reflects real, non-duplicated payments.

• Trigger/input: gateway webhook delivery.
• Observable result: the wallet is credited idempotently and a ledger entry is written; the Wallet view reflects the updated balance.
• Access state: system process triggered by the gateway; the Streamer observes the result in Wallet.
• Failure/recovery: duplicate webhook deliveries are deduplicated by idempotency key; missing confirmation leaves the top-up pending with a visible pending state.
• Continuation: confirmed credit enables per-stream charges.

Streaming and Milestone Settlement

FR-6 — HLS.js adaptive-bitrate playback (explicit) As a Streamer, I should watch content through the HLS.js player in the Streaming Player View, so that I get adaptive-bitrate streaming.

• Trigger/input: selecting and playing a content item.
• Observable result: playback begins with adaptive bitrate; the navbar shows the live wallet balance.
• Access state: authenticated, role-restricted to Streamer.
• Failure/recovery: stream load failure shows an error with retry.
• Continuation: playback proceeds and watch time is tracked (FR-7).

FR-7 — Secure watch-time tracking with seek/scrub handling (explicit) As a Streamer, I should have my watch time tracked accurately even when I seek or scrub, so that milestone detection reflects genuine viewing.

• Trigger/input: playback progress events, including seeks and scrubs.
• Observable result: accumulated watch time is computed against the content duration.
• Access state: authenticated, role-restricted to Streamer.
• Failure/recovery: anomalous progress is not counted toward the milestone.
• Continuation: accumulated watch time feeds milestone detection (FR-8).

FR-8 — Signed heartbeat at ≥ 70% watch completion (explicit) As a Streamer, I should have the client send a cryptographically signed heartbeat telemetry packet to POST /v1/telemetry/heartbeat when I reach at least 70% watch completion, so that the milestone is verifiable.

• Trigger/input: watch completion crossing the 70% threshold.
• Observable result: a signed heartbeat packet is sent to the backend.
• Access state: authenticated, role-restricted to Streamer.
• Failure/recovery: rejected telemetry shows a milestone error state; the client may retry.
• Continuation: validated telemetry triggers settlement (FR-9).

FR-9 — Atomic milestone settlement (explicit) As the platform, I should validate the heartbeat, deduct the per-stream fee from the streamer's wallet, and credit the creator's wallet minus platform commissions, so that watching produces a correct, atomic financial outcome.

• Trigger/input: validated heartbeat at POST /v1/telemetry/heartbeat.
• Observable result: the streamer's wallet is debited and the creator's wallet is credited (minus platform commissions); ledger entries are written atomically with row locking and idempotency keys.
• Access state: system process; the Streamer observes the balance change and the Creator observes the credit.
• Failure/recovery: insufficient streamer balance or invalid telemetry aborts settlement without partial writes; the Streamer is prompted to fund the wallet.
• Continuation: settled sessions appear in the Creator's micro-payout feed and the Admin's ledger.

FR-10 — Per-stream charge amounts (explicit) As the platform, I should charge\x20\xe2\x82\xa660 ($0.040 USD) for a full movie/series stream and\x20\xe2\x82\xa630 ($0.020 USD) for a season episode stream, so that pricing matches the specified tiers.

• Trigger/input: milestone settlement for the relevant content type.
• Observable result: the correct fee is deducted.
• Access state: system process.
• Failure/recovery: n/a beyond FR-9.
• Continuation: the fee flows into creator credit and platform commission.

Creator Earnings and Withdrawal

FR-11 — Real-time creator metrics (explicit) As a Creator, I should view real-time earnings, view counts, and a recent $0.022/$0.040 micro-payout activity feed via GET /v1/creator/metrics, so that I can monitor my income.

• Trigger/input: authenticated view of the Creator Studio Dashboard.
• Observable result: earnings cards, total views, and the micro-payout feed are displayed.
• Access state: authenticated, role-restricted to Creator.
• Failure/recovery: metrics fetch failure shows an error with retry.
• Continuation: metrics inform withdrawal decisions.

FR-12 — Withdrawal with live 40% fee-split preview (explicit) As a Creator, I should open the Withdrawal Modal and see the 40% platform fee and 60% net payout calculated live before I submit, so that I understand exactly what I will receive.

• Trigger/input: opening the Withdrawal Modal and entering an amount.
• Observable result: the 40% commission and 60% net are displayed live.
• Access state: authenticated, role-restricted to Creator.
• Failure/recovery: invalid amounts show inline validation.
• Continuation: confirmation submits the withdrawal (FR-13).

FR-13 — Withdrawal submission with commission routing and net dispatch (explicit) As a Creator, I should submit a withdrawal via POST /v1/creator/withdraw, so that the 40% commission is routed to the platform wallet and the 60% net is dispatched to me via Stripe Connect / Paystack payout APIs.

• Trigger/input: confirmed withdrawal submission.
• Observable result: ledger entries are logged; the 40% cut is routed to the platform wallet; the 60% net payout is dispatched via the payout provider.
• Access state: authenticated, role-restricted to Creator.
• Failure/recovery: payout dispatch failure is surfaced with a pending state and retry path; ledger entries remain consistent.
• Continuation: the Creator sees the updated balance and pending/completed payout state.

Administration

FR-14 — Executive financial KPIs (explicit) As an Admin, I should view Total Deposits, Gross Volume, 40% Platform Revenue, and Active User Balance Float via GET /v1/admin/analytics, so that I can oversee platform finances.

• Trigger/input: authenticated view of the Admin Control Center.
• Observable result: the four KPIs are displayed with tabular figures.
• Access state: authenticated, role-restricted to Admin.
• Failure/recovery: analytics fetch failure shows an error with retry.
• Continuation: KPIs inform audit review.

FR-15 — Real-time immutable ledger auditing table (explicit) As an Admin, I should audit a real-time ledger table showing timestamp, idempotency key fragment, debit account, credit account, amount, and immutable status, so that I can verify financial integrity.

• Trigger/input: authenticated view of the Admin Control Center.
• Observable result: ledger rows are displayed in fixed tabular columns; commission entries are visually marked.
• Access state: authenticated, role-restricted to Admin.
• Failure/recovery: fetch failure shows an error with retry.
• Continuation: the Admin can inspect individual rows.

Ledger Integrity

FR-16 — Immutable append-only double-entry ledger (explicit) As the platform, I should write every balance change to an immutable, append-only double-entry ledger with unique idempotency keys, so that double-spending and race conditions are prevented.

• Trigger/input: any wallet deduction or credit.
• Observable result: append-only ledger entries are written with unique idempotency keys.
• Access state: system process.
• Failure/recovery: duplicate idempotency keys are rejected; no partial writes occur.
• Continuation: the ledger is the authoritative record for all balances.

FR-17 — ACID row-locked wallet mutations (explicit) As the platform, I should use explicit row locking (SELECT ... FOR UPDATE) inside ACID database transactions for all wallet deductions and credits, so that concurrent mutations cannot corrupt balances.

• Trigger/input: any wallet deduction or credit.
• Observable result: mutations execute under row locks within transactions.
• Access state: system process.
• Failure/recovery: transaction rollback on failure leaves balances unchanged.
• Continuation: consistent balances feed all downstream views.

4. User Personas

Streamer (Viewer)

• Product context: A viewer on a Netflix-style platform who pays per stream from a prepaid wallet rather than a subscription. They fund the wallet via card or mobile money and watch full movies/series or season episodes through the HLS.js player.
• Primary goal: Uninterrupted playback with a live wallet balance and correct per-stream charges.
• Distinct accepted responsibilities: Funding the wallet (≥ $3.00, tiered AOV bundles); watching content; having watch time tracked accurately through seeks and scrubs; crossing the 70% milestone that triggers settlement.
• Relevant inputs/decisions: Bundle selection; content selection; whether to fund the wallet when balance is insufficient.
• Interactions with other participants: Their milestone settlement debits their wallet and credits the Creator's wallet (minus platform commissions); the resulting ledger entries are visible to the Admin.
• Observable success: Playback proceeds, the navbar shows the live balance, and the per-stream charge is correctly deducted at the 70% milestone.

Creator

• Product context: A content owner who earns micro-payouts when Streamers reach the 70% watch milestone on their content. They monitor earnings in the Creator Studio Dashboard and withdraw balances net of the 40% platform commission.
• Primary goal: Maximize and reliably withdraw earnings from qualified views.
• Distinct accepted responsibilities: Reviewing real-time earnings cards, total views, and the $0.022/$0.040 micro-payout feed; previewing the 40% fee split in the Withdrawal Modal; submitting withdrawals that route 40% to the platform wallet and dispatch 60% net via Stripe Connect / Paystack.
• Relevant inputs/decisions: Withdrawal amount; confirmation after previewing the split.
• Interactions with other participants: Receives credits from Streamer milestone settlements; their withdrawals generate commission revenue visible to the Admin.
• Observable success: Earnings and view counts update in real time; withdrawals show the correct 40/60 split and dispatch the net payout.

Admin

• Product context: A finance operator overseeing the platform's financial integrity. They work in the Admin Control Center reviewing executive KPIs and auditing the immutable ledger.
• Primary goal: Verify financial integrity and monitor platform revenue.
• Distinct accepted responsibilities: Reviewing Total Deposits, Gross Volume, 40% Platform Revenue, and Active User Balance Float; auditing the real-time ledger table with timestamp, idempotency key fragment, debit account, credit account, amount, and immutable status.
• Relevant inputs/decisions: Which ledger rows to inspect; whether KPIs indicate anomalies.
• Interactions with other participants: Observes the financial results of Streamer top-ups and milestone settlements and Creator withdrawals.
• Observable success: KPIs and ledger rows render accurately and in real time, with commission entries clearly marked.

5. Core User Flows

Flow A — Streamer enrolls and logs in

1. Streamer opens Landing (anonymous) and reads the pricing and creator-earnings explanation.
2. Streamer selects Sign Up and opens Sign Up.
3. Streamer chooses the streamer role and submits enrollment.
4. System creates the account; Streamer is routed to Login (or an authenticated session).
5. Streamer submits credentials to POST /v1/auth/login; a JWT is issued.
6. Streamer lands on the Streaming Player View.

• Failure/recovery: Validation or duplicate-account errors are shown inline on Sign Up; invalid credentials are shown inline on Login with the form preserved for retry.

Flow B — Streamer funds the wallet

1. Streamer opens Wallet (authenticated, Streamer role).
2. Streamer views the current balance_usd.
3. Streamer selects a tiered AOV bundle at or above the $3.00 minimum.
4. Streamer initiates payment via POST /v1/billing/create-intent and completes payment on the Stripe or Paystack gateway.
5. Gateway delivers a webhook to /webhook/stripe or /webhook/paystack.
6. System credits the wallet idempotently and writes a ledger entry.
7. Streamer sees the updated balance in Wallet and in the player navbar.

• Failure/recovery: Amounts below $3.00 are rejected; declined payments show an error and allow retry; missing webhook confirmation leaves a visible pending state.

Flow C — Streamer watches and triggers milestone settlement

1. Streamer opens Streaming Player View (authenticated, Streamer role) with a funded wallet.
2. Streamer selects a content item (full movie/series or season episode) and plays it via HLS.js.
3. Player tracks watch time, handling seeks and scrubs.
4. When watch completion reaches ≥ 70%, the client sends a cryptographically signed heartbeat to POST /v1/telemetry/heartbeat.
5. Backend validates the telemetry, deducts\x20\xe2\x82\xa660 ($0.040) for a full movie/series or\x20\xe2\x82\xa630 ($0.020) for a season episode from the Streamer's wallet under row locking, and credits the Creator's wallet minus platform commissions.
6. Ledger entries are written atomically with idempotency keys.
7. Streamer sees the updated navbar balance and milestone status.

• Failure/recovery: Insufficient balance prompts the Streamer to fund the Wallet and resume; rejected telemetry shows a milestone error with retry.

Flow D — Creator reviews earnings and withdraws

1. Creator opens Creator Studio Dashboard (authenticated, Creator role).
2. Dashboard loads GET /v1/creator/metrics, showing real-time earnings cards, total views, and the $0.022/$0.040 micro-payout feed.
3. Creator opens the Withdrawal Modal and enters an amount.
4. Modal calculates the 40% platform fee and 60% net payout live.
5. Creator confirms; the modal submits to POST /v1/creator/withdraw.
6. System logs ledger entries, routes the 40% cut to the platform wallet, and dispatches the 60% net via Stripe Connect / Paystack payout APIs.
7. Creator sees the updated balance and pending/completed payout state.

• Failure/recovery: Invalid amounts show inline validation; payout dispatch failure surfaces a pending state with a retry path while ledger entries remain consistent.

Flow E — Admin audits platform finances

1. Admin opens Admin Control Center (authenticated, Admin role).
2. Dashboard loads GET /v1/admin/analytics, showing Total Deposits, Gross Volume, 40% Platform Revenue, and Active User Balance Float.
3. Admin reviews the real-time ledger auditing table with timestamp, idempotency key fragment, debit account, credit account, amount, and immutable status.
4. Admin inspects individual rows; commission entries are visually marked.

• Failure/recovery: Analytics fetch failure shows an error with retry.

6. Visuals Colors and Theme

Muse: Rasmus Andersson. Headline: Graphite product craft for streaming money in motion.

The product reads as a dark, Netflix-style streaming platform that also feels like an auditable financial instrument: exact, fast, dense, and visibly accountable.

Color tokens (dark mode)

Blue is avoided entirely. Netflix-red imitation branding is avoided.

Typography

• Headings: Space Grotesk, 600–700 weight, tight -0.045em tracking; large sentence-case display headlines; compact uppercase status labels; tabular numerals for all monetary, timecode, and ledger values.
• Body: Geist.
• Scale (clamp-based): 48px mobile → 104px desktop for the landing/display headline; 30px → 52px for dashboard KPI values; 20px → 28px section headings; 16px body; 13px ledger labels; 11px uppercase metadata. All display text wraps cleanly at 375px.

Shape language

Hard-edged cinematic panels with 8px radii only where touch affordance benefits from rounding. 1px graphite-grey rules, dense metadata rails, square thumbnail frames, compact segmented controls, and a signature acid-green 2px active edge. Financial figures sit in monospaced tabular columns rather than decorative cards.

Layout

Responsive operational shell: narrow left rail at desktop, compact top command bar on tablet, bottom navigation dock on mobile. The player page uses a wide 16:9 media field above a precise transaction-and-watch-status rail. Creator and admin views use an asymmetric 12-column desktop grid: one large financial statement region, a narrower live activity rail, and compact KPI strips rather than repeated equal cards. At 375px, modules become a single vertical sequence with horizontally scrollable ledger tables and metric strips.

Imagery

High-contrast film stills with deep blacks for media rows, contrasted with precise schematic playback telemetry, waveform strips, receipt-like ledger records, and watch-session timelines. No stock business photography, floating abstract blobs, glass panels, or generic 3D objects.

7. Signature Design Concept

The public entry is a full-viewport graphite control-room composition rather than a conventional marketing hero. A cropped 16:9 streaming frame occupies the left two-thirds at desktop, with an oversized Space Grotesk headline stacked across the lower edge reading "WATCH. SETTLE. CREATE." at 48px on mobile through 104px on desktop. The right third is a live-looking vertical settlement rail showing a wallet balance, a 70% watch threshold line, creator credit, and platform fee entries in tabular figures. An acid-green playback line cuts horizontally from the video frame into the ledger rail, visually turning viewing progress into a verified transaction. On mobile, the readable headline and wallet panel stack below the media frame; the image may crop, but no labels or controls do.

This concept recomposes only accepted content — the pricing tiers, the 70% milestone, the 40% commission, and the wallet balance — into a single legible statement of how watching becomes money.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: The cropped 16:9 streaming frame and the vertical settlement rail, joined by the acid-green playback line.
• Input → transformation → outcome thesis: As the playback line advances across the video frame, it crosses the 70% threshold line and continues into the ledger rail, where a creator credit and a platform fee entry settle into place — turning viewing progress into a verified transaction.
• Motion vocabulary: Fast, functional 140–180ms transitions; a thin acid line advancing playback progress; a single tangerine-to-chartreuse settlement flash on the ledger entry when the payout is confirmed; count-up used once on authenticated dashboard load, then direct value updates.
• Composed first frame: The video frame at rest with the headline stacked across its lower edge, the settlement rail showing a wallet balance and the 70% threshold line, and the playback line paused just before the threshold.
• Reduced-motion state: Settlement flashes are removed and progress is displayed as a static line; the ledger rail shows the settled state without animation.

9. Non-Functional Requirements

• Ledger immutability (explicit): The ledger is append-only; no balance change may bypass it. Rationale: financial integrity and auditability.
• Row-locked ACID transactions (explicit): All wallet deductions and credits use SELECT ... FOR UPDATE inside database transactions. Rationale: prevent race conditions and double-spending.
• Idempotency keys (explicit): Every ledger transaction carries a unique idempotency key. Rationale: prevent duplicate settlement from retried webhooks or heartbeats.
• Bot-manipulation resistance (explicit): Telemetry heartbeats are cryptographically signed and validated server-side; watch-time deltas are validated. Rationale: prevent fraudulent milestone payouts.
• Numeric precision (explicit): balance_usd uses numeric precision 12,4. Rationale: accurate micro-transaction accounting.
• Dark Netflix-style UI (explicit): The UI is dark-themed and Netflix-style, built with React/Next.js and Tailwind CSS.
• Production readiness (explicit): Code is clean, modular, heavily commented, and ready for production deployment.
• Readable text and controls (explicit): Headlines, wordmarks, labels, numbers, cards' text and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit; no other element covers them. Imagery and decoration may crop or bleed.

10. Tech Stack

• Frontend: React / Next.js with Tailwind CSS; HLS.js for adaptive-bitrate playback (VideoPlayer.jsx, CreatorDashboard.jsx, AdminDashboard.jsx).
• Backend: Node.js / Express REST API exposing POST /v1/auth/login, POST /v1/billing/create-intent, /webhook/stripe, /webhook/paystack, POST /v1/telemetry/heartbeat, GET /v1/creator/metrics, POST /v1/creator/withdraw, and GET /v1/admin/analytics.
• Database: PostgreSQL with an immutable double-entry ledger schema (Users, Wallets, Ledger Transactions), using raw SQL or Prisma/Sequelize.
• Payments: Stripe and Paystack for card and mobile money top-ups; Stripe Connect / Paystack payout APIs for net creator payouts.
• Deployment: docker-compose.yml spinning up PostgreSQL and the Node.js backend container.

11. Assumptions and Constraints

• Assumption: The initial scaffold lists a FastAPI backend and MariaDB; the authoritative requirement thread explicitly specifies Node.js/Express and PostgreSQL, which take precedence for this product's backend and database.
• Assumption: The platform wallet is a system-owned wallet that receives the 40% commission on withdrawals.
• Assumption: Tiered AOV bundle values above the $3.00 minimum are not enumerated in the source and are treated as configurable tiers.
• Constraint: Minimum top-up is $3.00.
• Constraint: Per-stream charge is\x20\xe2\x82\xa660 ($0.040 USD) for a full movie/series and\x20\xe2\x82\xa630 ($0.020 USD) for a season episode.
• Constraint: Payout is triggered only at ≥ 70% watch completion, validated from a cryptographically signed heartbeat.
• Constraint: A 40% platform commission is deducted upon withdrawal, with 60% net dispatched to the creator and the 40% cut routed to the platform wallet.
• Constraint: The system must be secure against race conditions and bot manipulation.
• Constraint: The UI must be dark-themed and Netflix-style.

12. Glossary

• Streamer (Viewer): A user who watches content and pays per-stream charges from a prepaid wallet.
• Creator: A user who earns micro-payouts when Streamers reach the 70% milestone on their content and withdraws net of the 40% commission.
• Admin: A user who oversees platform finances and audits the ledger.
• Wallet: A user's balance record (balance_usd, numeric 12,4).
• Ledger Transaction: An immutable, append-only double-entry record with a unique idempotency key.
• Idempotency Key: A unique identifier preventing duplicate ledger writes from retried requests.
• 70% Watch Milestone: The completion threshold at which a signed heartbeat triggers settlement.
• Heartbeat: A cryptographically signed telemetry packet sent by the client at the milestone.
• Platform Commission: The 40% cut deducted on withdrawal and routed to the platform wallet.
• Net Payout: The 60% remainder dispatched to the creator via Stripe Connect / Paystack.
• AOV Bundle: A tiered top-up amount at or above the $3.00 minimum.
• HLS.js: The adaptive-bitrate streaming library used by the player.