System Requirements Document for emails-google-search

1. Introduction

emails-google-search is a working email extractor: an operator-facing application that searches for emails through Google search links online and extracts them at scale, with a hard target of over 5 million emails. The product is a control-room instrument for a single kind of power user — the Email Extraction Operator — who configures and launches extraction runs against Google search links, watches the harvested count climb toward the 5-million target, and then reviews and takes away the collected email list.

The intent is not a marketing site or a friendly consumer app. It is a dense, keyboard-first operator console where live counts, run states, and email rows are the content. The audience is a data-harvesting developer/operator who lives inside the tool for hours while long-running extraction runs execute in the background.

This document is the System Requirements Document for the product; it specifies the features and workflows in full, including the self-service identity that makes durable, owner-specific runs and results reachable, the backend execution that performs the extraction, and the durable storage of runs and results.

2. System Overview

2a. Product Interpretation and Delivery Boundary

The application is delivered as a first-party web product with a shared backend. The frontend is a React application UI; the backend is a single shared FastAPI process that hosts the application APIs and domain modules, including the extraction engine that searches Google search links online and extracts emails; MariaDB holds application-owned persistent data (operators, runs, and extracted email results); Redis provides the accepted shared state, queue, and coordination need for background extraction work and live progress.

Access is application-owned. The Landing page is anonymous and explains the extractor, its Google-search-link sourcing, and its 5-million-email target before sign-in. Sign Up and Login are anonymous identity-access surfaces: Sign Up establishes first-use identity, and Login verifies a returning operator so they can reach their durable runs and results. Extraction Runs, Run Progress, and Results require login, because runs and their harvested emails are durable, owner-specific state that must remain bound to the correct operator and be resumable across sessions.

Extraction itself is background automation: once an operator launches a run, the backend executes the Google-search-link search and email extraction asynchronously, and the operator observes progress and results through the first-party pages. The current delivery horizon covers the full lifecycle from anonymous landing through enrollment, run configuration and launch, progress monitoring toward the 5-million-email target, and review of extracted results. No future-horizon capabilities are currently accepted.

2b. Source Content Inventory

Not applicable — no reference directive with content_source was supplied.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry. Explains the email extractor, that emails are sourced through Google search links online, and the over-5-million-email target. Presents the hero console: an UPPERCASE 12px tangerine micro-label "GOOGLE-SEARCH-LINK EXTRACTION", a Space Grotesk headline "Five million emails, pulled from the index." stacked over three lines, and a single-line Inter Tight subtext capped at 52ch. A right-third instrument panel shows a JetBrains Mono counter ticking toward 5,000,000 with the target as denominator, a hairline pipeline schematic (query → SERP links → crawl → extract → dedupe → store) with tangerine nodes, and a small run-state pill.
• Primary actions: Navigate to Sign Up to begin; navigate to Login for returning operators.
• Supporting actions: Read the sourcing explanation and target statement; view the pipeline schematic.
• Domain entities: None persisted on this page; it presents the product concept and target.
• Component responsibilities: Hero block (micro-label, headline, subtext); live-looking counter card overlapping the hero's bottom hairline rule by 24px; pipeline schematic divider; run-state pill; primary CTA to Sign Up; secondary link to Login.
• States: Loading — static content, no data fetch required; Empty — not applicable; Success — page renders fully; Error — not applicable; Recovery — not applicable.

Sign Up

• Information/state: Anonymous self-service enrollment form for a new Email Extraction Operator. Collects the credentials needed to establish application-owned identity.
• Primary actions: Submit enrollment to create the operator's account and establish first-use identity.
• Supporting actions: Navigate to Login if already enrolled; return to Landing.
• Domain entities: Operator (new account).
• Component responsibilities: Enrollment form with labeled inputs on the 8-pt grid (32/36/40px heights, 6px radii); submit button with tangerine primary fill; inline validation messaging; link to Login.
• States: Loading — submit in progress with disabled control; Empty — blank form; Success — account created and operator proceeds to protected work; Error — invalid or already-used credentials shown inline with recovery guidance; Recovery — correct input and resubmit, or switch to Login.

Login

• Information/state: Anonymous returning-verification form for an existing Email Extraction Operator.
• Primary actions: Submit credentials to verify identity and reach durable runs and results.
• Supporting actions: Navigate to Sign Up if not yet enrolled; return to Landing.
• Domain entities: Operator (existing account).
• Component responsibilities: Credential form with labeled inputs; submit button; inline error messaging; link to Sign Up.
• States: Loading — verification in progress with disabled control; Empty — blank form; Success — verified and routed to Extraction Runs; Error — invalid credentials shown inline without revealing which field failed; Recovery — retry, or navigate to Sign Up.

Extraction Runs

• Information/state: Authenticated owner for configuring and launching an extraction run that searches Google search links online. Lists the operator's runs with run name, run state pill (RUNNING in tangerine, QUEUED in muted, COMPLETE in desaturated green), and harvested count in tabular numerals. Opens with a full-width status header strip: run name left, live counter right in JetBrains Mono at display size. Two-thirds / one-third split: run list on the left, configuration panel pinned on the right.
• Primary actions: Configure a new run (search query / Google search link inputs and run parameters) and launch it; open an existing run's progress.
• Supporting actions: Review run history and states; navigate to Results for completed runs.
• Domain entities: Extraction Run (name, query/link inputs, state, harvested count, target), Operator.
• Component responsibilities: Status header strip; run list table with hairline row rules, tabular numerals, slashed zeros, hover row fill to #1C1E21, and a 3px tangerine bar on the active run row; configuration panel with labeled inputs and launch button; status pills.
• States: Loading — run list skeleton with hairline placeholders; Empty — no runs yet, with a prompt to configure the first run; Success — run created and queued, with state pill and counter updating; Error — invalid configuration or launch failure shown inline with retry; Recovery — correct configuration and relaunch.

Run Progress

• Information/state: Authenticated owner for monitoring a launched run's progress toward the 5-million-email target. Shows the run name, live harvested counter in JetBrains Mono at display size, a 1px tangerine progress rule advancing under the run header, run-state pill, and yield sparkline / density histogram drawn in hairline strokes.
• Primary actions: Observe live progress and state; continue to Results when the run completes.
• Supporting actions: Return to Extraction Runs; review run metadata (source, yield).
• Domain entities: Extraction Run (state, harvested count, target, progress), extracted email count.
• Component responsibilities: Status header strip with live counter; progress rule; status pill with 120ms cross-fade on state change; sparkline and histogram components; navigation to Results.
• States: Loading — progress fetch in flight with counter placeholder; Empty — run queued with zero harvested; Success — counter rolling up and progress rule advancing; Error — progress unavailable shown with retry; Recovery — retry fetch or return to Extraction Runs.

Results

• Information/state: Authenticated owner for viewing and accessing the extracted email results of completed runs. Dense table of extracted emails with monospace email addresses, tabular numerals, slashed zeros, and hairline row rules; summary panel pinned on the right with total count and target status.
• Primary actions: Browse and access the extracted email list for a completed run.
• Supporting actions: Select among the operator's completed runs; review total count against the 5-million target.
• Domain entities: Extracted Email (address, source run), Extraction Run.
• Component responsibilities: Results table (the only horizontally scrollable region; stacked label/value rows at 375px); summary panel; run selector; status pill.
• States: Loading — table skeleton; Empty — no results for the selected run, with guidance to check Run Progress; Success — email rows rendered with counts; Error — results unavailable shown with retry; Recovery — retry or reselect a run.

3. Functional Requirements

FR-1 — Search for emails through Google search links online (explicit) As an Email Extraction Operator, I should launch an extraction run that searches for emails through Google search links online, so that the harvested addresses come from live web search results.

• Trigger/input: Operator submits a run configuration containing the search query / Google search link inputs on Extraction Runs.
• Observable result: A new Extraction Run is created in QUEUED state and the backend begins searching Google search links online.
• Access state: Requires login.
• Failure/recovery: Invalid configuration is rejected inline with guidance; the operator corrects and relaunches.
• Continuation: The run proceeds to Run Progress for monitoring.

FR-2 — Extract emails from the search results (explicit) As an Email Extraction Operator, I should have emails extracted from the search results of my run, so that I obtain a usable email list.

• Trigger/input: The backend processes the Google search links returned for the run's query.
• Observable result: Extracted email addresses are recorded against the run and counted in the live counter.
• Access state: Requires login to view; extraction executes in the backend.
• Failure/recovery: Extraction errors surface as a run error state on Run Progress with retry guidance.
• Continuation: Extracted emails become available on Results.

FR-3 — Support extracting over 5 million emails (explicit) As an Email Extraction Operator, I should be able to run extraction at a scale that reaches over 5 million emails, so that the hard target is met.

• Trigger/input: A launched run whose harvested count accumulates toward and beyond 5,000,000.
• Observable result: The live counter and progress rule track the count against the 5,000,000 denominator; the run continues until the target is exceeded.
• Access state: Requires login.
• Failure/recovery: If the run stalls or errors before the target, the operator sees the state and can retry.
• Continuation: Completion is observable on Run Progress and Results.

FR-4 — Working extractor (explicit) As an Email Extraction Operator, I should use a working extractor end to end, so that launching, monitoring, and retrieving results all function.

• Trigger/input: The operator completes the full lifecycle from Landing through Sign Up/Login, run launch, progress, and results.
• Observable result: Each stage produces its observable state and the final email list is available.
• Access state: Anonymous for Landing/Sign Up/Login; login for protected pages.
• Failure/recovery: Each stage provides inline error and retry.
• Continuation: The operator can revisit durable runs and results after returning.

FR-5 — Self-service enrollment before first protected extraction work (required_inference) As a new Email Extraction Operator, I should enroll myself on Sign Up before doing protected extraction work, so that my runs and results are bound to me.

• Trigger/input: Anonymous visitor submits the Sign Up form.
• Observable result: An application-owned operator account is created and the operator proceeds to protected work.
• Access state: Anonymous entry; establishes identity.
• Failure/recovery: Invalid or duplicate credentials shown inline; correct and resubmit or switch to Login.
• Continuation: Operator reaches Extraction Runs.

FR-6 — Returning verification before accessing durable runs and results (required_inference) As a returning Email Extraction Operator, I should verify my identity on Login, so that I can reach my durable runs and results.

• Trigger/input: Operator submits credentials on Login.
• Observable result: Identity is verified and the operator is routed to Extraction Runs with their own runs and results.
• Access state: Anonymous entry; grants access to protected pages.
• Failure/recovery: Invalid credentials shown inline without revealing which field failed; retry or go to Sign Up.
• Continuation: Operator resumes monitoring or reviews results.

FR-7 — Backend execution of Google-search-link extraction and durable storage of runs and results (required_inference) As an Email Extraction Operator, I should have my runs executed in the background and their runs and results stored durably, so that I can monitor progress and return later to the harvested emails.

• Trigger/input: A launched run is enqueued and processed by the backend.
• Observable result: Run state, harvested counts, and extracted emails persist in MariaDB and are reflected on Run Progress and Results.
• Access state: Backend execution; results visible only to the owning operator under login.
• Failure/recovery: Transient failures are retried; persistent failures surface as a run error state.
• Continuation: The operator can leave and return to find the run's durable state.

4. User Personas

Email Extraction Operator

• Product context: A data-harvesting developer/operator who runs the extractor as an instrument for hours at a time. They work in a dense, keyboard-first console and care about live counts, run states, and email rows rather than marketing polish.
• Primary goal: Launch extraction runs that search Google search links online and harvest over 5 million emails, then take away the collected email list.
• Distinct accepted responsibilities: Enrolls via Sign Up and verifies via Login; configures and launches runs on Extraction Runs; monitors progress toward the 5-million target on Run Progress; reviews and accesses extracted emails on Results.
• Relevant inputs or decisions: Search query / Google search link inputs and run parameters; when to launch, retry, or move to results.
• Interactions with other accepted participants: The operator is the sole active human persona; the backend executes extraction and the application owns identity and durable state on the operator's behalf.
• Observable success: The extraction run completes with the harvested count exceeding 5,000,000 and the email list is available on Results.

5. Core User Flows

Flow A — First-time operator enrolls and launches a run

1. The visitor opens Landing anonymously and reads the extractor explanation, the Google-search-link sourcing, and the 5-million-email target in the hero console.
2. The visitor selects the primary CTA and arrives at Sign Up.
3. The operator completes the enrollment form and submits. On success, an application-owned account is created and the operator is routed to Extraction Runs. On error, inline guidance appears and the operator corrects and resubmits.
4. On Extraction Runs, the operator configures a new run with the search query / Google search link inputs and run parameters in the right-hand configuration panel.
5. The operator launches the run. A new run appears in the list in QUEUED state with a status pill, and the backend begins searching Google search links online.
6. The operator opens the run and continues to Run Progress.

Flow B — Operator monitors progress toward 5 million emails

1. On Run Progress, the operator sees the run name in the status header strip and the live harvested counter in JetBrains Mono at display size, with 5,000,000 as the denominator.
2. As the backend extracts emails from the search results, the counter rolls up in place and the 1px tangerine progress rule advances under the run header; the status pill cross-fades to RUNNING.
3. The operator watches the yield sparkline and density histogram to gauge progress.
4. If progress becomes unavailable, an error state appears with retry; the operator retries or returns to Extraction Runs.
5. When the count exceeds 5,000,000, the status pill cross-fades to COMPLETE and the operator continues to Results.

Flow C — Returning operator verifies and reviews results

1. The returning operator opens Login anonymously and submits credentials.
2. On success, the operator is routed to Extraction Runs and sees their durable runs and states. On error, inline guidance appears without revealing which field failed; the operator retries or navigates to Sign Up.
3. The operator selects a completed run and opens Results.
4. On Results, the operator browses the dense table of extracted emails with monospace addresses and tabular numerals, and reviews the total count against the 5-million target in the summary panel.
5. If results are unavailable, an error state appears with retry; the operator retries or reselects a run.

6. Visuals Colors and Theme

Muse: Rasmus Andersson. Headline: "Five million emails, pulled from the index."

Mode: Dark.

Colour tokens (exact hex by role):

• Background (page ground): #141517 (graphite)
• Surface (panels, run cards, table rows): #1C1E21
• Hairline borders: #2A2D31
• Text (ink, full strength): #F2EFE9
• Primary: #F2EFE9
• Accent (single hot signal): #FF6B2C (tangerine)
• Muted (labels, metadata, secondary numerals; never below 14px): #8A8F98
• Success (status pills only, never a button fill): #7BBF8A (desaturated green)

Proportion: ~80% graphite/ink, ~15% muted, ~5% tangerine. The accent reads as a warning light on an instrument, not a brand colour.

Typography:

• Headings: Space Grotesk, 500–700, tracking -0.03em; sentence case for section titles; UPPERCASE at 12px / 0.14em tracking for micro-labels (RUN STATE, SOURCE, YIELD).
• Body: Inter Tight for prose and controls.
• Numerals: JetBrains Mono for every count, ID, timestamp, and email address; tabular numerals with slashed zero.
• Scale (1.25 modular with display jump): 12 / 14 / 16 / 20 / 25 / 31 / 48 / clamp(44px, 6.5vw, 88px) for the hero counter.

Shape language: Compact and machined — 6px radii on inputs and buttons, 10px on panels, 2px on status pills and tags. Hairline 1px borders do all separating work; no drop shadows, no glass, no rounded blobs. Controls on an 8-pt grid at 32/36/40px heights. A single 3px tangerine bar marks the active run row and the top edge of the primary panel — the only thick stroke in the system.

Spacing rhythm: 12-column content grid with a fixed 24px gutter; 8-pt spacing increments.

Imagery style: No photography, no illustration, no 3D. Imagery is the interface itself: a 1px-stroke pipeline schematic (query → SERP links → crawl → extract → dedupe → store) with tangerine nodes, sparkline yield charts, and a density histogram of extracted emails in hairline strokes. Decoration limited to a faint 24px dot-grid on the hero ground and the tangerine signal bar.

Layout: Persistent left rail — 72px collapsed icon rail at 375px, 232px labelled rail at ≥1024px — with wordmark top-left. Pages open with a full-width status header strip (run name left, live counter right in JetBrains Mono at display size). Below it, a two-thirds / one-third split: dense data table or run list left, configuration or summary panel pinned right. Tables are the primary layout primitive. At 375px the rail collapses to a bottom tab bar and tables become stacked label/value rows; nothing scrolls horizontally except the email list itself.

Avoid: Any blue, indigo, or violet; white or near-white page grounds; gradient blobs, glass, frosted cards, soft shadows; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, system-ui; grids of identical hover-lift cards; centred headline + subtext + pill-button heroes; decorative illustration, 3D renders, or stock photography; bouncy or springy motion; anything slower than 200ms on a state change.

7. Signature Design Concept

The public entry is a dark graphite console, not a marketing band. Left two-thirds, anchored hard left and flush to the grid: an UPPERCASE 12px tangerine micro-label "GOOGLE-SEARCH-LINK EXTRACTION", then a Space Grotesk headline at clamp(44px, 6.5vw, 88px) reading "Five million emails, pulled from the index." stacked over three lines with tight leading, and beneath it a single-line Inter Tight subtext capped at 52ch.

Right third: a live-looking instrument panel — a bordered #1C1E21 card with a JetBrains Mono counter ticking toward 5,000,000 (target as denominator), a hairline pipeline schematic with tangerine nodes, and a small run-state pill. The counter card overlaps the hero's bottom hairline rule by 24px so the composition reads as one machined object rather than a card floating on a gradient. No centred text, no blue button, no blob. The 1px pipeline schematic is reused as the section divider between every major block on the landing page.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: The live tabular-numeral counter card ticking toward 5,000,000, with the hairline pipeline schematic beneath it.
• Input → transformation → outcome thesis: As the page settles, the counter digits roll up in place toward the target and the 1px tangerine progress rule advances under the run header, communicating the product's defining state — a harvest climbing toward five million — without introducing any behavior beyond the accepted extraction lifecycle.
• Motion vocabulary: Fast and functional — 140ms ease-out on hover fills, 180ms on panel reveals, no bounce, no parallax, no decorative loops. The one permitted continuous motion is the live counter (digits roll up in place) plus the 1px tangerine progress rule. Status changes cross-fade their pill colour in 120ms.
• Composed first frame: Graphite ground with faint 24px dot-grid; micro-label, three-line headline, and subtext flush left; instrument card on the right overlapping the hero's bottom hairline by 24px; counter at rest showing its starting value with the target as denominator.
• Reduced-motion state: With prefers-reduced-motion, the counter and progress rule snap to their final values with no roll, and panel reveals appear instantly.

9. Non-Functional Requirements

• Scale target (explicit): Extraction must reach over 5 million emails per the hard constraint; the counter, progress rule, and results table must handle counts beyond 5,000,000 with tabular numerals and slashed zeros.
• Sourcing constraint (explicit): Emails must be sourced through Google search links online; the backend must perform the search and extraction against those links.
• Durable state (planning scope): Runs, harvested counts, and extracted emails must persist in MariaDB so operators can resume and revisit after returning.
• Shared state/queue (planning scope): Redis is required for the accepted shared caching, state, queue, or coordination need supporting background extraction and live progress.
• Background automation (planning scope): Extraction runs execute asynchronously in the backend so the operator can monitor progress and leave/return.
• Identity continuity (required_inference): Application-owned identity with self-service enrollment and returning verification protects durable, owner-specific runs and results.
• Accessibility: Readable text and controls stay whole at 375px, 768px, and 1280px; status is conveyed by UPPERCASE label text, not colour alone; prefers-reduced-motion is respected.
• Performance: State changes complete within 200ms; hover fills 140ms ease-out; panel reveals 180ms; status pill cross-fade 120ms.

10. Tech Stack

• Frontend: React application UI.
• Backend: Shared FastAPI process hosting application APIs and domain modules, including the extraction engine that searches Google search links online and extracts emails.
• Database: MariaDB for application-owned persistent data (operators, runs, extracted emails).
• Cache/queue/coordination: Redis for the accepted shared caching, state, queue, or coordination need.
• Deployment: docker-compose with the provisioned services — backend, database, frontend, redis.

11. Assumptions and Constraints

• Assumption (narrow): The single active human persona is the Email Extraction Operator; the backend and application act on the operator's behalf. (required_inference)
• Assumption (narrow): Application-owned identity is established via self-service Sign Up and verified via Login, protecting only Extraction Runs, Run Progress, and Results. (required_inference)
• Constraint (explicit): Extraction must reach over 5 million emails.
• Constraint (explicit): Emails must be sourced through Google search links online.
• Constraint (planning scope): Durable state is required; Redis is required; authentication is required; backend integration is required.
• Constraint (design): The generic indigo/blue-on-white SaaS template is forbidden; the graphite/tangerine instrument-panel direction is authoritative.

12. Glossary

• Email Extraction Operator: The sole active human persona who configures, launches, monitors, and reviews extraction runs.
• Extraction Run: A configured, launched job that searches Google search links online and extracts emails, tracked from QUEUED through RUNNING to COMPLETE.
• Google search link: A web search result link returned for a run's query, from which emails are extracted.
• Harvested count: The number of emails extracted so far in a run, displayed in the live counter against the 5,000,000 target.
• 5-million-email target: The hard constraint that extraction must reach over 5 million emails.
• Pipeline schematic: The 1px-stroke diagram query → SERP links → crawl → extract → dedupe → store with tangerine nodes.
• Status pill: The only rounded-2px element, carrying state in UPPERCASE 12px label text (RUNNING tangerine, QUEUED muted, COMPLETE desaturated green).