System Requirements Document for recoveros-revenue

1. Introduction

RecoverOS is a real, working full-stack SaaS web application and installable PWA whose tagline is "Find the revenue your business is already losing." Its product intent is to help a business recover missed leads, forgotten follow-ups, abandoned opportunities, and inactive customers using that business's own real data — never fabricated data.

The product's defining commitment is evidentiary honesty. It must never create fake customers, fake revenue, fake analytics, fake integrations, fake API responses, or fake email-sent statuses. When something requires credentials or configuration that is not present, the product shows SETUP REQUIRED rather than pretending it works. When evidence for a claim is missing, agents return INSUFFICIENT DATA. Estimated opportunity value is never presented as verified revenue.

The audience is small and mid-size operators (e-commerce, agencies, service businesses) who already hold real customer records but have no system watching them for recoverable revenue. The primary users are the people who connect or import real business data, review detected opportunities with their real evidence, approve or reject AI-drafted recovery messages, run campaigns, maintain suppression and compliance controls, and track verified recovered revenue.

The core working flow the product must make real end to end is:

REAL BUSINESS DATA → CONNECT/IMPORT → OPPORTUNITY DETECTION → REAL EVIDENCE → AI RECOMMENDATION → MESSAGE DRAFT → HUMAN APPROVAL → REAL EMAIL → REAL EVENT → VERIFIED OUTCOME

2. System Overview

RecoverOS is delivered as a multi-tenant SaaS application with a public marketing entry, application-owned identity, a protected application shell, real data connections, six core AI agents, a human-approved email pipeline with real provider event tracking, e-commerce recovery opportunity detection, an audit log, and tenant-isolated PostgreSQL/Supabase-compatible storage. It is prepared for deployment on GitHub + Supabase + Cloudflare Pages/Workers, and ships with README, .env.example, database schema, migrations, API documentation, and deployment instructions.

Actors. The accepted active human personas are the Revenue Recovery Operator, the Campaign Manager, the Compliance & Data Steward, and the Organization Administrator. External systems that participate but are not personas include the configured email provider, the connected data sources (Google Sheets, Gmail, HubSpot, Pipedrive, Salesforce, Shopify, WooCommerce, REST APIs, inbound webhooks), and the AI model services backing the six agents.

Accepted behavior. Users establish an organization and secure session, connect or import real business data, run agents that detect opportunities and produce evidence-backed recommendations and drafts, approve messages before any send, send through a real configured provider, receive real delivery events (message ID, timestamp, delivery status, bounce, unsubscribe), and see verified recovered revenue separated from estimated opportunity value. Campaigns move through DRAFT, READY, PAUSED, RUNNING, COMPLETED, ERROR. Follow-up sequences stop on unsubscribe, bounce, negative response, or manual stop. Every sensitive action is recorded in the audit log.

Ownership. The application owns identity, tenant data, agent orchestration, approval gating, campaign lifecycle, suppression, audit, and settings. The configured email provider owns actual delivery and delivery-event truth. Connected sources own the records they supply. AI model services own generation only; they never own evidence or verification.

Narrow exclusions. No fake testimonials, fake customer logos, or fake statistics anywhere. No fabricated numbers on the Dashboard. No demo data mixed with production data. No passwords, API keys, or OAuth tokens in frontend code. No cross-tenant data access. No e-commerce recovery opportunity type created without real connected data supporting it. No "Sent" status without real provider confirmation. No "CONNECTED" status without a real successful connection.

2a. Product Interpretation and Delivery Boundary

RecoverOS is a first-party application with application-owned identity. Because the accepted journeys require durable, tenant-scoped state — organizations, memberships, connections, opportunities, drafts, approvals, sends, events, suppression entries, and audit records — a user must establish an organization and a secure session before any protected work, and must be able to return and resume that work later. Self-service enrollment is the accepted bootstrap because no invitation or provisioning boundary is established for initial product use.

Access is therefore split into an anonymous entry boundary (the public Landing page, plus Login and Sign Up for establishing or verifying identity) and a protected application boundary (Dashboard, Opportunities, Opportunity Details, Customers, CSV Import, Campaigns, Campaign Details, Suppression List, Connections, AI Agents, Analytics, Audit Log, Settings). Protected destinations are role-restricted within the tenant; the anonymous entry surfaces are not. A protected destination never owns the interaction that establishes access to itself.

Delivery is real and provider-backed. Where a capability depends on an external credential or configuration that is absent — an email provider, an OAuth app, a store connection, an AI model key — the product surfaces SETUP REQUIRED and does not simulate success. Demo mode exists only as an explicitly labeled, isolated mode that displays "DEMO MODE — DATA IS NOT REAL" and never mixes with production data.

Current scope covers everything described in this document. No future-horizon features are asserted beyond the current commitments.

2b. Source Content Inventory

Not applicable. No reference directive in this project declares a content_source; all product facts derive from the authoritative user requirement thread and the accepted Planning Scope.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Hero headline "Find the revenue your business is already losing."; subtitle "Recover missed leads, forgotten follow-ups, abandoned opportunities and inactive customers using your business's real data."; buttons "Start Free Recovery Scan" and "See How It Works". Numbered sections 01–10: Problem, How It Works, AI Agents, Integrations, Industries, Dashboard, Security, Pricing, FAQ, CTA. A full-bleed hairline strip listing the ten connection names (CSV, Google Sheets, Gmail, HubSpot, Pipedrive, Salesforce, Shopify, WooCommerce, REST API, Webhooks) with honest status dots. A real UI plate titled "RECOVERY PIPELINE" showing the seven numbered stages with honest state chips and the final stage "VERIFIED OUTCOME" marked with the warning accent and the muted line "Awaiting first verified event".
• Primary actions: "Start Free Recovery Scan" (routes to Sign Up); "See How It Works" (scrolls to the How It Works section).
• Supporting actions: Navigate to Login; open FAQ items; jump to Pricing, Security, Integrations, Industries, Dashboard, AI Agents, CTA.
• Domain entities: None persisted. Content describes organizations, opportunities, agents, integrations, campaigns, and verified revenue conceptually.
• Component responsibilities: Numbered section marker (28px circle, white numeral); hero headline block with purple rule; primary and outlined pill buttons; schematic recovery-loop diagram (connect → detect → evidence → draft → approve → send → verified) drawn as a numbered linear diagram; transit-line connections strip; faithful non-fake UI plates for Dashboard and How It Works showing real empty/connected copy.
• States: Loading — skeleton shimmer on the UI plates while any real content is fetched. Empty — UI plates show the real empty copy ("SETUP REQUIRED", "No real business data connected yet."). Success — sections render with real copy only. Error — if a plate cannot load real content, it shows SETUP REQUIRED rather than a placeholder. Recovery — retry loads the real state.
• Constraints: No fake testimonials, fake customer logos, or fake statistics. No placeholder numbers. No chart renders without a real query behind it.

Login

• Information/state: Anonymous identity-access surface for returning users. Email and password fields; error region; link to Sign Up.
• Primary actions: Submit credentials to establish a secure session.
• Supporting actions: Navigate to Sign Up; navigate back to Landing.
• Domain entities: users, organizations, organization_members.
• Component responsibilities: Credential form; validation messaging; session establishment; redirect to Dashboard on success.
• States: Loading — submit disabled with inline progress. Empty — initial form. Success — session established, redirect to Dashboard. Error — invalid credentials or unverified account shown inline without revealing which field is wrong beyond a generic message. Recovery — user may retry; repeated failures are recorded in the audit log.
• Constraints: Passwords never exposed in frontend code. No credential values logged.

Sign Up

• Information/state: Anonymous identity-access surface for first use. Fields to establish a user and an organization; link to Login.
• Primary actions: Create the user, create the organization, create the organization membership, and establish a secure session.
• Supporting actions: Navigate to Login; navigate back to Landing.
• Domain entities: users, organizations, organization_members.
• Component responsibilities: Enrollment form; organization creation; membership creation; session establishment; redirect to Dashboard.
• States: Loading — submit disabled with inline progress. Empty — initial form. Success — organization and session established, redirect to Dashboard. Error — duplicate account, invalid input, or provisioning failure shown inline. Recovery — user may retry or switch to Login.
• Constraints: No passwords, API keys, or OAuth tokens in frontend code. Tenant is created for the enrolling user only.

Dashboard

• Information/state: Five metric cards in a single row, each with an 11px uppercase label, a 39px/700 tabular numeral right-aligned, and a 1px hairline under the label: Revenue At Risk, Opportunities Found, High Priority, Follow-ups Due, Verified Recovered Revenue. When the database holds no real data, every card shows an em dash and the single line "No real business data connected yet."
• Primary actions: Open a metric's underlying list (Opportunities, Campaigns, Analytics).
• Supporting actions: Navigate to Connections to connect a source; navigate to AI Agents to run detection.
• Domain entities: opportunities, campaigns, messages, email_events, customers, deals, orders, invoices.
• Component responsibilities: Metric card with tabular numeral; empty-state line; count-up animation on mount over 600ms only when values arrive from a real query and never from a fake starting value; links into the owning lists.
• States: Loading — skeleton shimmer in the exact geometry of the five cards. Empty — em dashes plus "No real business data connected yet." Success — real values from the tenant's database. Error — the affected card shows SETUP REQUIRED or an error line, never a zero dressed as data. Recovery — retry re-queries.
• Constraints: Only real database values. Never fake numbers. Verified Recovered Revenue is never populated from estimated opportunity value.

Opportunities

• Information/state: Table of detected lost-revenue opportunities with type (Abandoned Cart, Abandoned Checkout, Inactive Customer, Repeat Purchase, Failed Payment), customer, estimated value, priority, and status. Sticky header, 48px rows, hairline dividers, right-aligned tabular numerals, status as dot plus uppercase chip.
• Primary actions: Open an opportunity's details; expand a row inline to reveal the raw source records backing the opportunity (table name, record id, timestamp) above the AI recommendation and the draft.
• Supporting actions: Filter by type, priority, and status; sort; navigate to AI Agents to run the Opportunity Detector.
• Domain entities: opportunities, customers, contacts, leads, deals, orders, invoices, agent_runs.
• Component responsibilities: Data table; inline evidence panel (not a modal); status chip; empty-state line with the honest next action.
• States: Loading — skeleton rows. Empty — "No real business data connected yet." with a "Connect a source" action. Success — real rows. Error — error line with retry. Recovery — retry re-queries; INSUFFICIENT DATA opportunities are shown with the warning chip rather than hidden.
• Constraints: Only opportunities supported by real connected data. Never invent evidence.

Opportunity Details

• Information/state: Independently revisitable view of one opportunity: type, customer, estimated value, priority, status, the raw source records backing it (table name, record id, timestamp), the AI recommendation, and the current draft. When evidence is missing, the view shows INSUFFICIENT DATA.
• Primary actions: Run or re-run the Customer Researcher and Recovery Writer for this opportunity; create or edit a message draft; submit the draft for approval.
• Supporting actions: Navigate back to Opportunities; open the related customer; open the related campaign.
• Domain entities: opportunities, customers, contacts, messages, agent_runs, audit_logs.
• Component responsibilities: Evidence list; recommendation block; draft editor; approval submission; INSUFFICIENT DATA chip.
• States: Loading — skeleton. Empty — no draft yet, with the honest next action. Success — evidence, recommendation, and draft present. Error — provider or agent failure shown with SETUP REQUIRED where credentials are missing. Recovery — re-run agents; drafts are preserved.
• Constraints: Never invent evidence or customer information. Estimated value is never labeled verified revenue.

Customers

• Information/state: Table of customers and contacts from authorized records with factual context: name, email, company, last contact, status, deal value, last message, customer ID, order ID where present.
• Primary actions: Open a customer's factual context; start a recovery draft from that context.
• Supporting actions: Search, filter, sort; navigate to CSV Import or Connections to add data.
• Domain entities: customers, contacts, leads, deals, orders, invoices, messages.
• Component responsibilities: Data table; customer context panel; draft initiation; empty-state line.
• States: Loading — skeleton rows. Empty — "No real business data connected yet." with a "Connect a source" action. Success — real rows. Error — error line with retry. Recovery — retry re-queries.
• Constraints: Factual context from authorized data only. Never invent customer information.

CSV Import

• Information/state: Upload and mapping surface for CSV files supporting the fields Name, Email, Company, Last Contact, Status, Deal Value, Last Message, Customer ID, Order ID. Shows a mapping step, a validation summary, and an import result with imported/skipped/errors counts.
• Primary actions: Upload a CSV; map columns to the supported fields; run validation; confirm the import.
• Supporting actions: Download an error report; re-map and retry; navigate to Customers to review imported rows.
• Domain entities: customers, contacts, leads, deals, orders, messages, audit_logs.
• Component responsibilities: File upload; column mapper; duplicate and invalid-email validator; result summary; error report.
• States: Loading — parsing progress. Empty — no file selected. Success — imported/skipped/errors counts with per-row reasons. Error — invalid file, unmappable columns, or validation failure shown with reasons. Recovery — fix mapping or file and re-run; skipped rows are never silently dropped.
• Constraints: Duplicates and invalid emails must be validated and reported. Import is recorded in the audit log.

Campaigns

• Information/state: Table of campaigns with status DRAFT, READY, PAUSED, RUNNING, COMPLETED, ERROR; audience size, message count, and delivery summary where real events exist.
• Primary actions: Create a campaign; move it through the lifecycle; open Campaign Details.
• Supporting actions: Filter by status; pause or resume; navigate to AI Agents to draft messages.
• Domain entities: campaigns, messages, email_events, opportunities, customers, audit_logs.
• Component responsibilities: Campaign table; status chip; lifecycle controls; empty-state line.
• States: Loading — skeleton rows. Empty — no campaigns yet, with the honest next action. Success — real rows. Error — ERROR status with the real failure reason. Recovery — fix the cause and re-run; failures are recorded in the audit log.
• Constraints: Human approval is ON by default. A campaign cannot send without approval.

Campaign Details

• Information/state: Focused view of one campaign: audience, message list with per-message approval state, provider events (message ID, timestamp, delivery status, bounce, unsubscribe), and the approved follow-up sequence with its stop conditions.
• Primary actions: Approve or reject individual messages; start, pause, resume, or stop the campaign; stop a follow-up sequence manually.
• Supporting actions: Edit a draft; open the related opportunity or customer; navigate back to Campaigns.
• Domain entities: campaigns, messages, email_events, suppression_list, audit_logs.
• Component responsibilities: Message list; approval controls; event timeline; follow-up sequence controls; stop-condition display.
• States: Loading — skeleton. Empty — no messages yet. Success — messages with real provider events. Error — provider failure shown with SETUP REQUIRED where credentials are missing. Recovery — retry send; the sequence stops on unsubscribe, bounce, negative response, or manual stop.
• Constraints: Never show "Sent" unless the real provider confirms it. Record message ID, timestamp, delivery status, bounce, and unsubscribe when available.

Suppression List

• Information/state: Durable list of suppressed addresses and unsubscribe states that block communication, with source and timestamp per entry.
• Primary actions: Add a suppression entry; remove an entry where permitted; review unsubscribe status.
• Supporting actions: Search and filter; export; navigate to Audit Log for related events.
• Domain entities: suppression_list, email_events, audit_logs.
• Component responsibilities: Suppression table; add/remove controls; unsubscribe state display; empty-state line.
• States: Loading — skeleton rows. Empty — no suppressed addresses. Success — real entries. Error — error line with retry. Recovery — retry; changes are recorded in the audit log.
• Constraints: Suppression blocks communication. Compliance Guard checks this list before any communication.

Connections

• Information/state: One row per supported connection — CSV, Google Sheets, Gmail, HubSpot, Pipedrive, Salesforce, Shopify, WooCommerce, REST API, Webhooks — each with status NOT CONNECTED, CONNECTING, CONNECTED, or ERROR, plus configuration state and last-checked time.
• Primary actions: Configure and connect a source; disconnect; re-check status; open CSV Import for CSV.
• Supporting actions: Enter REST API and webhook configuration; verify webhook signatures; navigate to Customers to review imported data.
• Domain entities: integrations, customers, contacts, leads, deals, orders, invoices, audit_logs.
• Component responsibilities: Connection row with status chip; configuration form; OAuth initiation; webhook verification; status polling that pulses only while genuinely CONNECTING.
• States: Loading — skeleton rows. Empty — all rows NOT CONNECTED. Success — CONNECTED only after a real successful connection. Error — ERROR with the real reason; SETUP REQUIRED where credentials are missing. Recovery — retry connection; statuses are recorded in the audit log.
• Constraints: Never show CONNECTED unless the real connection succeeds. Never expose API keys or OAuth tokens in frontend code. Secure OAuth and webhook verification.

AI Agents

• Information/state: The six core agents with their purpose, last run, and result state: Opportunity Detector, Customer Researcher, Recovery Writer, Follow-up Agent, Revenue Analyzer, Compliance Guard. Each run shows its inputs, outputs, and INSUFFICIENT DATA where evidence is missing.
• Primary actions: Run an agent against authorized data; review its output; act on its recommendation.
• Supporting actions: Open the related opportunity, customer, or campaign; review agent run history.
• Domain entities: agents, agent_runs, opportunities, customers, messages, campaigns, suppression_list, audit_logs.
• Component responsibilities: Agent cards; run controls; run history; INSUFFICIENT DATA chip; SETUP REQUIRED where a model or provider credential is missing.
• States: Loading — skeleton. Empty — no runs yet. Success — real outputs. Error — real failure reason; SETUP REQUIRED where credentials are missing. Recovery — re-run; every run is recorded in the audit log.
• Constraints: Agents never invent evidence or customer information. Missing evidence returns INSUFFICIENT DATA. Revenue Analyzer never calls estimated value verified revenue. Compliance Guard checks approval, suppression list, unsubscribe status, duplicate contact, sending limits, and available evidence before communication.

Analytics

• Information/state: Charts and tables separating real-record opportunity values from verified recovered revenue, with the five-step purple ramp and the single highlight series for verified outcomes. No chart renders without a real query behind it.
• Primary actions: Filter by period, source, and opportunity type; drill into an underlying record.
• Supporting actions: Export; navigate to Opportunities or Campaigns.
• Domain entities: opportunities, deals, orders, invoices, messages, email_events, campaigns.
• Component responsibilities: Chart components; comparison table; empty-state line; verified-versus-estimated labeling.
• States: Loading — skeleton chart geometry. Empty — "No real business data connected yet." Success — real charts. Error — error line with retry. Recovery — retry re-queries.
• Constraints: Never call estimated value verified revenue. Never render a chart without a real query.

Audit Log

• Information/state: Chronological record of login, imports, integrations, agent runs, drafts, approvals, sends, failures, unsubscribe, and verified revenue events, with actor, timestamp, and affected record.
• Primary actions: Filter and search events; open the related record.
• Supporting actions: Export; navigate to the related page.
• Domain entities: audit_logs, email_events, agent_runs, integrations, suppression_list.
• Component responsibilities: Event table; filters; record links; empty-state line.
• States: Loading — skeleton rows. Empty — no events yet. Success — real events. Error — error line with retry. Recovery — retry re-queries.
• Constraints: Every listed event type is recorded. No credential values are logged.

Settings

• Information/state: Tenant configuration: organization profile, membership and roles, security-related settings, demo-mode indicator, and integration credential status (never credential values).
• Primary actions: Manage organization membership and roles; update settings; toggle demo mode where permitted.
• Supporting actions: Navigate to Connections for integration configuration; navigate to Audit Log for related events.
• Domain entities: organizations, organization_members, users, settings, integrations, audit_logs.
• Component responsibilities: Membership table; role controls; settings form; demo-mode banner; credential-status display.
• States: Loading — skeleton. Empty — initial settings. Success — saved settings. Error — validation or authorization error shown inline. Recovery — retry; changes are recorded in the audit log.
• Constraints: Secrets stay server-side. Tenant isolation holds. Demo mode, when enabled, displays "DEMO MODE — DATA IS NOT REAL" and never mixes with production data.

3. Functional Requirements

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

FR-1 — Real working application. As a Revenue Recovery Operator, I should use a real, working full-stack SaaS web app and PWA named RecoverOS with the tagline "Find the revenue your business is already losing," so that I can act on real business data rather than a mockup. Provenance: explicit. Trigger: opening the product. Observable result: the application performs real operations against real configured services. Failure/recovery: where a capability needs credentials or configuration, it shows SETUP REQUIRED. Continuation: the user proceeds with the parts that are configured.

FR-2 — No fabricated data. As a Revenue Recovery Operator, I should never be shown fake customers, fake revenue, fake analytics, fake integrations, fake API responses, or fake email-sent statuses, so that every number and status I see is trustworthy. Provenance: explicit. Trigger: any data display. Observable result: only real values or an honest empty/SETUP REQUIRED state. Failure/recovery: missing configuration yields SETUP REQUIRED. Continuation: the user configures the missing piece.

FR-3 — Never invent business information. As a Revenue Recovery Operator, I should see SETUP REQUIRED whenever something needs credentials or is not configured, so that I am never misled about what the system actually knows. Provenance: explicit. Trigger: an unconfigured dependency. Observable result: SETUP REQUIRED is displayed. Failure/recovery: configuring the dependency clears the state. Continuation: the user retries the action.

FR-4 — Premium B2B SaaS design. As a Revenue Recovery Operator, I should use an interface built with the specified purple palette (#6D28D9, #8B5CF6, #4C1D95, #FFFFFF, #FAF9FF, #111827, #6B7280), premium typography, large whitespace, rounded cards, subtle shadows, professional charts, clean icons, responsive layouts, smooth page transitions, subtle hover animations, skeleton loading, and accessible high contrast, so that the product feels like premium enterprise software. Provenance: explicit. Trigger: any screen. Observable result: the design system is applied consistently. Failure/recovery: not applicable. Continuation: the user continues working.

FR-5 — RecoverOS logo. As a Revenue Recovery Operator, I should see a professional RecoverOS logo with an abstract recovery/loop symbol that does not copy another company's branding, so that the product is identifiable and original. Provenance: explicit. Trigger: any branded surface. Observable result: the logo renders legibly from favicon to lockup. Failure/recovery: not applicable. Continuation: the user continues.

FR-6 — Landing page. As a visitor, I should see a landing page with the hero headline "Find the revenue your business is already losing.", the subtitle "Recover missed leads, forgotten follow-ups, abandoned opportunities and inactive customers using your business's real data.", the buttons "Start Free Recovery Scan" and "See How It Works", and the sections Problem, How It Works, AI Agents, Integrations, Industries, Dashboard, Security, Pricing, FAQ, and CTA, so that I understand the product before signing up. Provenance: explicit. Trigger: visiting the public entry. Observable result: the hero, buttons, and all ten sections render. Failure/recovery: not applicable. Continuation: the visitor starts a free recovery scan or reads how it works.

FR-7 — No fake social proof. As a visitor, I should never see fake testimonials, fake customer logos, or fake statistics, so that my trust is not manipulated. Provenance: explicit. Trigger: any landing content. Observable result: only real, verifiable content or none. Failure/recovery: not applicable. Continuation: the visitor continues reading.

FR-8 — App navigation. As a Revenue Recovery Operator, I should navigate Dashboard, Opportunities, Customers, Campaigns, Connections, AI Agents, Analytics, Audit Log, and Settings, so that I can reach every part of the product. Provenance: explicit. Trigger: using the app shell. Observable result: all nine destinations are reachable. Failure/recovery: not applicable. Continuation: the user moves between sections.

FR-9 — Mobile responsive and installable PWA. As a Revenue Recovery Operator, I should use the entire application on mobile and install it as a PWA, so that I can work from any device. Provenance: explicit. Trigger: opening on a mobile device or installing. Observable result: responsive layouts and installability. Failure/recovery: not applicable. Continuation: the user continues working.

**