System Requirements Document for jobpilot-ai

1. Introduction

JobPilot AI is a working web application that automates a single job seeker's end-to-end job search and application workflow. The product intent is a supervised autonomous agent: it finds jobs, checks match, customizes resumes, prepares applications, asks for approval, submits, tracks results, and monitors replies — working automatically as much as possible while interrupting the owner only for missing or uncertain information, login/CAPTCHA/MFA/manual verification, websites that do not support automation, and final application approval.

The governing rule is: the AI searches, prepares, and manages everything possible automatically; the owner controls what is finally submitted or sent. No application is ever submitted automatically, and no email is ever sent without approval.

The audience is a single technically literate job seeker (the Job Seeker (Owner)) who runs an autonomous agent across job portals, ATS platforms, company career pages, and Gmail, and who needs dense, stateful, approval-gated software — a control room, not a marketing site.

2. System Overview

JobPilot AI is delivered as a first-party web application with an application-owned identity, a backend that performs scheduled and long-running automation, and secure provider integrations for job portals and Gmail. The current delivery includes:

• A public entry surface (Landing) and self-service identity surfaces (Sign Up, Login).
• A protected console of working surfaces: Dashboard, Jobs, Match Review, Career Profile, Resume Studio, Application Prep, Approval Queue, Connections, Monitoring, Email Inbox, Reply Drafts, Recruiters, and Applications.
• A floating AI chat button present on every page that can find relevant jobs, search company career pages, check visa sponsorship, customize resumes, prepare applications, check Gmail for recruiter replies, update application tracking, and prepare follow-up emails.
• Backend scheduling that runs continuous monitoring even when the dashboard is closed, when backend scheduling is configured.
• Provider-owned authorization for job portals and Gmail via OAuth, APIs, or permitted integrations; passwords and API secrets are never exposed in frontend code.

Actors are the Job Seeker (Owner) as the sole active human persona, plus typed non-persona actors: supported job sources and ATS platforms (LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, Workday, Greenhouse, Lever), Gmail, and the backend automation/scheduler.

Narrow exclusions: the product never bypasses CAPTCHA, MFA, anti-bot protection, authentication restrictions, or website security controls; it never invents missing information or email addresses; it never submits an application or sends an email without explicit approval; it never marks an application as submitted without confirmation; and it prevents duplicate applications.

2a. Product Interpretation and Delivery Boundary

JobPilot AI is a supervised automation console. The agent does the searching, matching, tailoring, form-filling, and monitoring; the human holds the trigger. Everything that requires a human decision — final submission, sending a recruiter email, resolving an unknown application question, completing a login/CAPTCHA/MFA step, or supplying missing information — is surfaced to the owner as an explicit interruption with a clear next action.

Delivery is first-party web software with application-owned identity: the owner enrolls themselves, verifies on return, and then owns durable career, application, integration, and approval state. Provider-owned work (portal authorization, Gmail authorization, portal-side submission mechanics) stays with the provider via OAuth, APIs, or permitted integrations. Backend scheduling owns recurring monitoring when configured, so monitoring continues while the dashboard is closed.

Current scope is the full workflow described in this document. No future-horizon features are claimed; anything not stated here is out of current scope.

2b. Source Content Inventory

Not applicable — no reference directive declares content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression explaining JobPilot AI, its audience, and its automated-but-user-controlled workflow. Control-room header composition: full-bleed graphite ground, a 6px full-width tangerine "agent is live" rule pinned at the very top, an oversized Space Grotesk tabular metric ("47 JOBS FOUND TODAY" style) left-aligned and bleeding toward the right edge, a muted second line beneath it summarizing strong matches, prepared applications, and approvals awaiting the owner, and a live agent status panel to the right (dropping below at 768px and 375px) with a monospace action log and a tangerine progress rule.
• Primary actions: Enter the product via the single primary CTA ("Review N approvals" style, solid tangerine, 2px radius) leading to Login; proceed to Sign Up for first-time enrollment.
• Supporting actions: Read the workflow band (Find → Match → Tailor → Approve → Submit → Track) drawn as a ruled horizontal band with the active stage in tangerine; read the safety statement (never bypasses CAPTCHA/MFA/anti-bot/security controls; never submits without approval).
• Domain entities: Workflow stages, agent activity log lines, headline metrics.
• Component responsibilities: Hero metric block (tabular numerals, clamp sizing), agent status panel (monospace log + progress rule), workflow band, safety statement band, primary CTA.
• States: Loading (metric/log placeholders as ruled bands, no spinners-on-cards); empty (no live agent activity — status panel shows an idle monospace line and the progress rule is static); success (metrics and log render); error (if live metrics are unavailable, the metric band shows an explicit unavailable state rather than fabricated numbers); recovery (retry affordance on the metric band).

Login

• Information/state: Returning verification surface for the Job Seeker (Owner). Anonymous access; no protected state is shown before identity is established.
• Primary actions: Verify returning identity and enter the protected console.
• Supporting actions: Navigate to Sign Up if the owner has no account.
• Domain entities: Owner identity credential.
• Component responsibilities: Credential form (2px radii, hairline borders), submit control, link to Sign Up, inline error region.
• States: Loading (submit disabled with a monospace status line); empty (blank form); success (redirect into the protected console); error (invalid credentials shown inline without revealing which field is wrong); recovery (retry, and a path to Sign Up).

Sign Up

• Information/state: Self-service enrollment surface for the Job Seeker (Owner). Anonymous access.
• Primary actions: Establish the owner's application identity so durable career, application, integration, and approval state can be privately owned and resumed.
• Supporting actions: Navigate to Login if the owner already has an account.
• Domain entities: Owner identity credential.
• Component responsibilities: Enrollment form, submit control, link to Login, inline error region.
• States: Loading (submit disabled with a monospace status line); empty (blank form); success (identity established, then entry into the protected console); error (validation and duplicate-identity errors shown inline); recovery (correct and resubmit, or switch to Login).

Dashboard

• Information/state: Workflow summaries and analytics. Metric bands for jobs found today, strong matches, applications prepared, waiting for approval, applications submitted, recruiter replies, interviews, rejections, offers, and follow-ups due. Charts for applications by country, role, source, status, and time. A 12-column grid of metric bands (not a card grid); charts are flat, single-hue-plus-accent, drawn on the page ground with no chart junk.
• Primary actions: Read headline metrics; open the Approval Queue from the "waiting for approval" band; open Applications, Jobs, or Email Inbox from their respective bands.
• Supporting actions: Read the agent status strip (tangerine progress rule plus streaming monospace action log); read connection health and live sync timestamps in the left rail footer.
• Domain entities: Metric counts, chart series (country, role, source, status, time), agent activity log lines, connection health.
• Component responsibilities: Metric bands with 11px caps labels and right-aligned tabular numerals; headline numerals in Space Grotesk at display sizes; flat charts; agent status strip; left rail with connection health.
• States: Loading (ruled band skeletons with tabular placeholders); empty (zero-state bands with explicit "no data yet" monospace lines and empty charts drawn on the page ground); success (metrics and charts render, numerals count up once on entry, 300ms linear); error (per-band error with retry, other bands remain usable); recovery (retry the failed band; the agent status strip shows the last known action).

Jobs

• Information/state: Search results across supported sources — LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, and ATS platforms such as Workday, Greenhouse, and Lever. Filters for role, country, experience, salary, date posted, remote/hybrid/onsite, and visa sponsorship. Dense table with 11px caps column headers and right-aligned tabular numeric columns.
• Primary actions: Run a search; apply filters; open a job to review it; hand a job to Match Review.
• Supporting actions: Ask the floating AI chat to find relevant jobs or search company career pages; check visa sponsorship from the listing; open the original posting.
• Domain entities: Job listing (company, title, source, location, country, salary, date posted, work mode, visa sponsorship, job link, job description).
• Component responsibilities: Filter bar, results table, source column, visa-sponsorship indicator, row actions, floating AI chat button.
• States: Loading (table skeleton with ruled rows); empty (no results for the current filters, with a monospace explanation and a filter-reset action); success (results render with tabular alignment); error (source-level failure shown per source so partial results remain usable); recovery (retry the failed source; adjust filters).

Match Review

• Information/state: Job fit and match score evaluated against verified profile data. Shows the job, the match score, and the verified profile facts that produced the score.
• Primary actions: Review the match; accept the job for resume customization and application preparation; reject the match.
• Supporting actions: Ask the floating AI chat to check visa sponsorship or explain the match; open the original posting.
• Domain entities: Match score, verified profile facts, job listing.
• Component responsibilities: Score display (tabular numerals), evidence panel of verified facts, accept/reject controls, floating AI chat button.
• States: Loading (score placeholder as a ruled band); empty (no job selected — prompt to pick from Jobs); success (score and evidence render); error (if scoring cannot complete, show an explicit unscored state rather than a fabricated score); recovery (re-run scoring; return to Jobs).

Career Profile

• Information/state: Verified personal details, experience, education, skills and tools, certifications, preferred roles and locations, salary expectations, notice period, work authorization, visa sponsorship requirement, and master resume. Missing information is never invented; unset fields are visibly unset.
• Primary actions: Add, edit, and verify profile facts; upload and replace the master resume.
• Supporting actions: Ask the floating AI chat to customize resumes or prepare applications using this profile; review which facts are verified versus unset.
• Domain entities: Personal details, experience entries, education entries, skills and tools, certifications, preferred roles, preferred locations, salary expectations, notice period, work authorization, visa sponsorship requirement, master resume.
• Component responsibilities: Ruled label/value bands per section, edit controls, verification indicators, master resume upload, floating AI chat button.
• States: Loading (ruled band skeletons); empty (each section shows an explicit unset state with an add action); success (verified facts render with verification indicators); error (save failure shown inline with the unsaved value preserved); recovery (retry save; discard).

Resume Studio

• Information/state: Job-specific ATS-friendly resumes built only from verified information, plus cover letters. Resume version history, original vs customized comparison, and editing before use.
• Primary actions: Generate a tailored resume for a job; edit it before use; download as PDF or DOCX; create and edit a cover letter; compare original vs customized; select a version from history.
• Supporting actions: Ask the floating AI chat to customize resumes; return a chosen version to Application Prep.
• Domain entities: Resume version, cover letter, original master resume, comparison diff, download format (PDF/DOCX).
• Component responsibilities: Version history list, document panel with hairline rules and tabular metadata, diff view, editor, download controls, cover letter editor, floating AI chat button.
• States: Loading (document panel skeleton); empty (no versions yet — prompt to generate from a job); success (document renders with version metadata); error (generation or export failure shown inline, with the last good version preserved); recovery (retry generation or export; revert to a prior version).

Application Prep

• Information/state: Prepared applications for supported portals. The agent opens supported job portals, fills known information, uploads the correct resume, answers questions using the verified profile, and continues across application pages. Unknown questions stop that application and ask the owner. Interrupted work is saved and resumable via Open & Continue. The agent status strip shows the live action log (for example, "Workday · page 2/4 · 6 answers from profile · stopped: unknown question").
• Primary actions: Start or resume preparation; answer an unknown question when the agent stops; provide missing or uncertain information; use Open & Continue to resume saved progress; complete a login/CAPTCHA/MFA/manual verification step when required.
• Supporting actions: Ask the floating AI chat to prepare applications; open the portal page; send the prepared application to the Approval Queue.
• Domain entities: Prepared application, application page progress, answered questions, unknown questions, saved progress, portal, resume used.
• Component responsibilities: Preparation list, agent status strip (tangerine progress rule + monospace log), question/answer panel, interruption panel for missing information and verification, Open & Continue control, floating AI chat button.
• States: Loading (progress rule advancing with monospace log lines); empty (no applications in preparation — prompt to start from Jobs or Match Review); success (preparation completes and the application moves to the Approval Queue); error (portal does not support automation, or automation cannot continue — progress is saved and Open & Continue is offered); recovery (Open & Continue resumes from the saved step; manual verification is completed by the owner and preparation resumes).

Approval Queue

• Information/state: Prepared submissions awaiting the owner's decision. Before submission the owner sees company and job, application URL, resume, cover letter, personal information, application questions and answers, salary, visa/work authorization, and attachments. Two-pane split: evidence on the left, the control bar pinned full-width at the bottom, always visible, never scrolled away.
• Primary actions: Edit | Reject | Approve & Submit. Only after the owner selects Approve & Submit is the application submitted.
• Supporting actions: Open the application URL; inspect the resume version and cover letter; review each question and answer; review attachments; ask the floating AI chat to update application tracking.
• Domain entities: Prepared application, company, job, application URL, resume version, cover letter, personal information, application questions and answers, salary, visa/work authorization, attachments, approval decision.
• Component responsibilities: Evidence pane, pinned bottom control bar with Edit | Reject | Approve & Submit (Approve & Submit as the only solid tangerine control), monospace summary line above the bar listing exactly what will be sent (company, URL, resume version, cover letter hash, answers), floating AI chat button.
• States: Loading (evidence pane skeleton, control bar disabled); empty (nothing awaiting approval — explicit zero state); success (after Approve & Submit, the application is submitted and marked submitted only with confirmation); error (submission failure shown with the prepared application preserved and not marked submitted); recovery (retry submission; edit and re-approve; reject).

Connections

• Information/state: Secure connection of supported job portals via OAuth, APIs, or permitted integrations. Shows connection status, last sync, profile status, last search, applications prepared, and applications submitted. Passwords and API secrets are never exposed in frontend code.
• Primary actions: Connect a supported job portal; reconnect or disconnect; inspect connection status and activity.
• Supporting actions: Ask the floating AI chat to check Gmail for recruiter replies; open Monitoring to schedule searches on connected portals.
• Domain entities: Portal connection, connection status, last sync, profile status, last search, applications prepared, applications submitted.
• Component responsibilities: Ruled connection bands with 11px caps labels and right-aligned tabular values, connect/reconnect controls, provider authorization handoff, floating AI chat button.
• States: Loading (connection bands with pending status); empty (no portals connected — prompt to connect); success (status, last sync, and activity counts render; machine-confirmed connections use the lime truth color); error (authorization denied or expired — explicit status with a reconnect action); recovery (reconnect via the provider; refresh status).

Monitoring

• Information/state: Scheduled searches across selected job portals and company career pages. Schedule options are every hour, every 3 hours, every 6 hours, or daily. Monitoring runs even when the dashboard is closed, when backend scheduling is configured.
• Primary actions: Create a scheduled search; choose the interval (every hour / every 3 hours / every 6 hours / daily); select the portals and company career pages to monitor; enable or disable a schedule.
• Supporting actions: Ask the floating AI chat to find relevant jobs; open Jobs to review results from a run.
• Domain entities: Scheduled search, interval, selected portals, selected company career pages, last run, next run, run status.
• Component responsibilities: Schedule list with cron-style monospace expressions, interval selector, source selector, enable/disable controls, last/next run timestamps, floating AI chat button.
• States: Loading (schedule rows with pending run status); empty (no schedules — prompt to create one); success (schedule saved and next run shown); error (backend scheduling not configured — explicit state explaining that monitoring while the dashboard is closed requires backend scheduling to be configured); recovery (configure backend scheduling, then re-enable; or run a search on demand).

Email Inbox

• Information/state: Gmail-derived recruiter and application communications identified by category: recruiter emails, application confirmations, assessments, interviews, rejections, offers, and follow-ups.
• Primary actions: Connect Gmail securely; review messages by category; open a message; hand a message to Reply Drafts.
• Supporting actions: Ask the floating AI chat to check Gmail for recruiter replies; update application tracking from a message.
• Domain entities: Message, category (recruiter email, application confirmation, assessment, interview, rejection, offer, follow-up), sender, received time, linked application.
• Component responsibilities: Category bands, message list with tabular timestamps, message detail panel, Gmail connection control, floating AI chat button.
• States: Loading (message list skeleton); empty (no messages in a category — explicit zero state); success (messages render with categories); error (Gmail authorization expired or unavailable — explicit state with a reconnect action); recovery (reconnect Gmail; refresh).

Reply Drafts

• Information/state: Prepared recruiter email replies and drafts. Drafts are prepared but never sent without approval.
• Primary actions: Review a prepared reply; edit it; approve sending; discard.
• Supporting actions: Ask the floating AI chat to prepare follow-up emails; open the source message in Email Inbox.
• Domain entities: Draft reply, source message, recipient, approval decision.
• Component responsibilities: Draft editor, source-message reference, approval control, discard control, floating AI chat button.
• States: Loading (draft editor skeleton); empty (no drafts — prompt to prepare one from Email Inbox); success (draft saved; on approval, the email is sent and the draft is marked sent); error (send failure shown with the draft preserved and not marked sent); recovery (retry send; edit and re-approve; discard).

Recruiters

• Information/state: Legitimate publicly available recruiter/HR information showing name, role, company, email, source, and verification status. Email addresses are never invented.
• Primary actions: Find recruiter/HR information; review the source and verification status of each record; link a recruiter to an application.
• Supporting actions: Ask the floating AI chat to prepare follow-up emails; open the source.
• Domain entities: Recruiter record (name, role, company, email, source, verification status).
• Component responsibilities: Results table with 11px caps headers, source column, verification-status indicator (machine-verified records use the lime truth color), link-to-application control, floating AI chat button.
• States: Loading (table skeleton); empty (no records found — explicit zero state, never a fabricated record); success (records render with source and verification status); error (lookup failure shown inline); recovery (retry lookup; refine the query).

Applications

• Information/state: Durable application tracking records with company, job title, posting date, applied date, country/city, job link, job description, salary, INR salary conversion, visa sponsorship, work authorization, match score, resume used, recruiter, follow-up date, application status, and notes. Excel export to a real .xlsx file with filters, frozen headers, clickable job links, proper date/currency formatting, and separate sheets where useful.
• Primary actions: Browse and manage application records; edit status, follow-up date, recruiter, and notes; export to .xlsx.
• Supporting actions: Open the job link; open the resume used; ask the floating AI chat to update application tracking; open the Approval Queue for records waiting for approval.
• Domain entities: Application record (all tracked fields above), export file.
• Component responsibilities: Dense tracker table with 11px caps headers and right-aligned tabular numeric columns (salary, INR conversion, match score), row detail panel, export control, floating AI chat button.
• States: Loading (table skeleton); empty (no applications yet — explicit zero state); success (records render; export produces a real .xlsx with filters, frozen headers, clickable job links, proper date/currency formatting, and separate sheets where useful); error (export failure shown inline with the record set preserved); recovery (retry export; correct filters).

3. Functional Requirements

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

FR-1 — End-to-end automated workflow (explicit). As the Job Seeker (Owner), I should have JobPilot AI run the workflow find jobs → check match → customize resume → prepare application → ask for my approval → submit → track result → monitor replies, so that the whole search is managed for me. Lifecycle: initiated by the owner or by a scheduled run; the agent performs each stage; the owner is interrupted only for missing or uncertain information, login/CAPTCHA/MFA/manual verification, websites that do not support automation, and final application approval. Observable acceptance: each stage produces a visible state in the console, and the workflow advances without owner action until an interruption condition is met. Failure/recovery: if a stage cannot continue, progress is saved and Open & Continue is offered. Continuation: the workflow resumes from the saved stage.

FR-2 — Minimal interruption policy (explicit). As the Job Seeker (Owner), I should be interrupted only for missing or uncertain information, login/CAPTCHA/MFA/manual verification, websites that do not support automation, and final application approval, so that the agent works automatically as much as possible. Observable acceptance: no other interruption is raised during normal operation. Failure/recovery: an interruption always states what is needed and offers the action to resolve it. Continuation: after resolution, the agent resumes the interrupted work.

FR-3 — Floating AI chat on every page (explicit). As the Job Seeker (Owner), I should have a floating AI chat button on every page that can find relevant jobs, search company career pages, check visa sponsorship, customize resumes, prepare applications, check Gmail for recruiter replies, update application tracking, and prepare follow-up emails, so that I can drive the agent from anywhere. Observable acceptance: the button is present on every page and each listed action is invocable from it. Failure/recovery: if an action cannot be performed, the chat states why and what is needed. Continuation: the chat returns the result and the owner continues in the relevant page.

FR-4 — Job search across supported sources (explicit). As the Job Seeker (Owner), I should search supported sources — LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, and ATS platforms such as Workday, Greenhouse, and Lever — so that I see relevant openings in one place. Observable acceptance: results are returned per source with the source identified. Failure/recovery: a failing source is reported without discarding results from other sources. Continuation: the owner refines filters or opens a listing.

FR-5 — Job search filters (explicit). As the Job Seeker (Owner), I should filter by role, country, experience, salary, date posted, remote/hybrid/onsite, and visa sponsorship, so that results match my constraints. Observable acceptance: each filter narrows the result set and the active filters are visible. Failure/recovery: an over-narrow filter set produces an explicit empty state with a reset action. Continuation: the owner opens a result or adjusts filters.

FR-6 — Career Profile storage (explicit). As the Job Seeker (Owner), I should store my verified personal details, experience, education, skills and tools, certifications, preferred roles and locations, salary expectations, notice period, work authorization, visa sponsorship requirement, and master resume, so that the agent always works from verified facts. Observable acceptance: each listed section is stored and editable, and unset fields are visibly unset. Failure/recovery: a failed save preserves the entered value and reports the failure. Continuation: the owner retries or continues editing.

FR-7 — Never invent missing information (explicit). As the Job Seeker (Owner), I should never have missing information invented on my behalf, so that everything the agent produces is truthful. Observable acceptance: unset profile fields remain unset and are never filled with fabricated values in resumes, applications, or answers. Failure/recovery: when information is missing or uncertain, the agent stops and asks. Continuation: the owner supplies the information and the agent resumes.

FR-8 — Job-specific ATS-friendly resume (explicit). As the Job Seeker (Owner), I should get a job-specific ATS-friendly resume created using only verified information, so that each application is tailored without fabrication. Observable acceptance: the generated resume is tied to a specific job and contains only verified profile facts. Failure/recovery: if verified information is insufficient, generation stops and asks for the missing facts. Continuation: the owner supplies facts and generation completes.

FR-9 — Resume download, history, cover letters, comparison, editing (explicit). As the Job Seeker (Owner), I should download resumes as PDF or DOCX, keep resume version history, create cover letters, compare original vs customized, and edit before use, so that I control the final document. Observable acceptance: each capability is available on the generated resume, and edits are reflected in the version used for the application. Failure/recovery: a failed export or save preserves the last good version. Continuation: the owner retries or reverts to a prior version.

FR-10 — Automated application preparation (explicit). As the Job Seeker (Owner), I should have the AI open supported job portals, fill known information, upload the correct resume, answer questions using my verified profile, and continue across application pages, so that applications are prepared without manual form-filling. Observable acceptance: the prepared application contains the correct resume and answers drawn from the verified profile, and multi-page progress is visible. Failure/recovery: if a portal does not support automation or automation cannot continue, progress is saved and Open & Continue is offered. Continuation: the owner resumes via Open & Continue or completes the required manual step.

FR-11 — Unknown questions stop the application (explicit). As the Job Seeker (Owner), I should have the agent stop that application and ask me when it encounters an unknown question, so that no answer is invented. Observable acceptance: the application halts at the unknown question and the question is presented to the owner. Failure/recovery: the halted application retains its saved progress. Continuation: the owner answers and preparation resumes.

FR-12 — Mandatory approval before submission (explicit). As the Job Seeker (Owner), I should never have an application submitted automatically, and before submission I should see company and job, application URL, resume, cover letter, personal information, application questions and answers, salary, visa/work authorization, and attachments, with Edit | Reject | Approve & Submit, so that I control what is finally submitted. Observable acceptance: the application is submitted only after the owner selects Approve & Submit, and all listed evidence is shown before that decision. Failure/recovery: a submission failure leaves the prepared application intact and not marked submitted. Continuation: the owner retries, edits, or rejects.

FR-13 — Secure job portal connection (explicit). As the Job Seeker (Owner), I should securely connect supported job portals using OAuth, APIs, or permitted integrations, so that the agent can work on my behalf without exposing credentials. Observable acceptance: connections are established through the provider's authorization flow and no password or API secret appears in frontend code. Failure/recovery: denied or expired authorization is shown with a reconnect action. Continuation: the owner reconnects and the connection becomes usable again.

FR-14 — Connection and activity status (explicit). As the Job Seeker (Owner), I should see connection status, last sync, profile status, last search, applications prepared, and applications submitted for each connected portal, so that I know the agent's actual state. Observable acceptance: each listed value is displayed per connection. Failure/recovery: stale or failed sync is shown explicitly rather than as a healthy state. Continuation: the owner reconnects or triggers a sync.

FR-15 — Scheduled searches (explicit). As the Job Seeker (Owner), I should schedule searches every hour, every 3 hours, every 6 hours, or daily, so that monitoring runs on my cadence. Observable acceptance: the chosen interval is saved and the next run is shown. Failure/recovery: if backend scheduling is not configured, the schedule is shown as not running while the dashboard is closed. Continuation: the owner configures backend scheduling or runs a search on demand.

FR-16 — Monitoring while the dashboard is closed (explicit). As the Job Seeker (Owner), I should have selected job portals and company career pages monitored even when the dashboard is closed, when backend scheduling is configured, so that I do not miss openings. Observable acceptance: scheduled runs occur without the dashboard open when backend scheduling is configured, and their results appear in the console. Failure/recovery: a failed run is recorded with its failure reason. Continuation: the next scheduled run proceeds; the owner can review results in Jobs.

FR-17 — Gmail connection and message identification (explicit). As the Job Seeker (Owner), I should connect Gmail securely and have the agent identify recruiter emails, application confirmations, assessments, interviews, rejections, offers, and follow-ups, so that replies are monitored for me. Observable acceptance: messages are categorized into the listed categories. Failure/recovery: expired or unavailable Gmail authorization is shown with a reconnect action. Continuation: the owner reconnects and categorization resumes.

FR-18 — Replies and drafts without automatic sending (explicit). As the Job Seeker (Owner), I should have replies and drafts prepared but never sent without my approval, so that I control what is sent. Observable acceptance: a prepared reply is not sent until the owner approves it. Failure/recovery: a send failure preserves the draft and does not mark it sent. Continuation: the owner retries, edits, or discards.

FR-19 — Recruiter Finder (explicit). As the Job Seeker (Owner), I should find legitimate publicly available recruiter/HR information showing name, role, company, email, source, and verification status, so that I can reach real contacts. Observable acceptance: each record shows all six fields, and email addresses are never invented. Failure/recovery: when no legitimate record is found, the result is empty rather than fabricated. Continuation: the owner links a recruiter to an application or prepares a follow-up.

FR-20 — Application Tracker fields (explicit). As the Job Seeker (Owner), I should track company, job title, posting date, applied date, country/city, job link, job description, salary, INR salary conversion, visa sponsorship, work authorization, match score, resume used, recruiter, follow-up date, application status, and notes, so that every application is fully recorded. Observable acceptance: all listed fields are present on each record and editable. Failure/recovery: a failed edit preserves the prior value. Continuation: the owner retries the edit or continues to another record.

FR-21 — Excel export (explicit). As the Job Seeker (Owner), I should export applications to a real .xlsx file with filters, frozen headers, clickable job links, proper date/currency formatting, and separate sheets where useful, so that I can work with the data outside the app. Observable acceptance: the exported file opens as a real .xlsx and exhibits each listed property. Failure/recovery: an export failure is reported without altering the records. Continuation: the owner retries the export.

FR-22 — Dashboard metrics (explicit). As the Job Seeker (Owner), I should see jobs found today, strong matches, applications prepared, waiting for approval, applications submitted, recruiter replies, interviews, rejections, offers, and follow-ups due, so that I know where the workflow stands. Observable acceptance: each listed metric is displayed and reflects current state. Failure/recovery: a metric that cannot be computed is shown as unavailable rather than fabricated. Continuation: the owner opens the relevant page from the metric.

FR-23 — Dashboard charts (explicit). As the Job Seeker (Owner), I should see charts for applications by country, role, source, status, and time, so that I can read my pipeline at a glance. Observable acceptance: all five chart dimensions are available. Failure/recovery: a chart with no data renders an explicit empty state. Continuation: the owner filters or opens the underlying records.

FR-24 — Never bypass security controls (explicit). As the Job Seeker (Owner), I should never have CAPTCHA, MFA, anti-bot protection, authentication restrictions, or website security controls bypassed, so that the agent stays within legitimate automation. Observable acceptance: when such a control is encountered, the agent stops and asks the owner to complete it manually. Failure/recovery: the application's progress is saved. Continuation: the owner completes the verification and the agent resumes.

FR-25 — Save progress and Open & Continue (explicit). As the Job Seeker (Owner), I should have progress saved and an Open & Continue action provided when automation cannot continue, so that no work is lost. Observable acceptance: the interrupted application shows its saved step and offers Open & Continue. Failure/recovery: resuming from a saved step continues at that step. Continuation: the owner resumes or abandons the application.

FR-26 — Never mark submitted without confirmation (explicit). As the Job Seeker (Owner), I should never have an application marked as submitted without confirmation, so that my tracker reflects reality. Observable acceptance: an application's status becomes submitted only after confirmed submission following Approve & Submit. Failure/recovery: an unconfirmed submission leaves the status unchanged. Continuation: the owner retries or investigates the portal state.

FR-27 — Prevent duplicate applications (explicit). As the Job Seeker (Owner), I should be prevented from submitting duplicate applications, so that I do not apply twice to the same job. Observable acceptance: a job already applied to is flagged and cannot be submitted again. Failure/recovery: if a duplicate is detected during preparation, the application is stopped and the existing record is shown. Continuation: the owner reviews the existing application instead.

FR-28 — Self-service enrollment (required_inference). As the Job Seeker (Owner), I should be able to enroll myself so that my durable career, application, integration, and approval state is privately owned and resumable. Observable acceptance: enrollment establishes an application-owned identity and enters the protected console. Failure/recovery: validation and duplicate-identity errors are shown inline. Continuation: the owner corrects the error or switches to Login.

FR-29 — Returning verification (required_inference). As the Job Seeker (Owner), I should verify my identity on return before accessing protected workflow state, so that my state stays private. Observable acceptance: protected pages are inaccessible until verification succeeds. Failure/recovery: invalid credentials are shown inline without revealing which field is wrong. Continuation: the owner retries or switches to Sign Up.

FR-30 — Provider authorization for portals and Gmail (required_inference). As the Job Seeker (Owner), I should authorize job portals and Gmail through the provider's secure flow, so that the agent can act on my behalf without handling my secrets. Observable acceptance: authorization completes through the provider and no secret is exposed in frontend code. Failure/recovery: denied or expired authorization is shown with a reconnect action. Continuation: the owner reconnects.

FR-31 — Backend scheduling configuration (required_inference). As the Job Seeker (Owner), I should have backend scheduling configured so that monitoring runs while the dashboard is closed. Observable acceptance: when configured, scheduled runs occur without the dashboard open; when not configured, the console states this explicitly. Failure/recovery: a failed run is recorded with its reason. Continuation: the next run proceeds.

FR-32 — Manual completion of verification steps (required_inference). As the Job Seeker (Owner), I should complete CAPTCHA, MFA, login, or other verification manually when automation cannot proceed, so that the agent can continue legitimately. Observable acceptance: the agent stops at the verification step and presents it to the owner. Failure/recovery: progress is saved while the owner completes the step. Continuation: the agent resumes after completion.

FR-33 — Explicit approval before submission or sending (required_inference). As the Job Seeker (Owner), I should explicitly approve before any application is submitted or any email is sent, so that I hold the trigger. Observable acceptance: no submission or send occurs without an explicit approval action by the owner. Failure/recovery: a failed submission or send preserves the prepared artifact. Continuation: the owner retries, edits, or rejects.

4. User Personas

Job Seeker (Owner)

Product context. The sole active human user of JobPilot AI. This person runs a job search across multiple countries and portals, cares about visa sponsorship and work authorization, and is technically literate enough to want a control room rather than a guided wizard. They own the entire workflow: find jobs, check match, customize resume, prepare application, approve or reject submissions, track results, and monitor replies.

Primary goal. Have the agent search, prepare, and manage everything possible automatically, while personally controlling what is finally submitted or sent.

Distinct accepted responsibilities.

• Maintain verified career profile data — personal details, experience, education, skills and tools, certifications, preferred roles and locations, salary expectations, notice period, work authorization, visa sponsorship requirement, and master resume — and never let missing information be invented.
• Connect job portals and Gmail securely through OAuth, APIs, or permitted integrations, and inspect connection status, last sync, profile status, last search, applications prepared, and applications submitted.
• Configure scheduled searches at every hour, every 3 hours, every 6 hours, or daily across selected portals and company career pages.
• Review prepared applications and decide Edit | Reject | Approve & Submit, seeing company and job, application URL, resume, cover letter, personal information, application questions and answers, salary, visa/work authorization, and attachments before deciding.
• Review prepared recruiter replies and drafts and approve or withhold sending.
• Resolve interruptions: missing or uncertain information, login/CAPTCHA/MFA/manual verification, and websites that do not support automation.
• Track applications across all tracked fields and export them to .xlsx.

Relevant inputs or decisions. Verified profile facts; search filters (role, country, experience, salary, date posted, remote/hybrid/onsite, visa sponsorship); schedule intervals; approval decisions; answers to unknown application questions; manual verification completion; recruiter follow-up decisions.

Interactions with other accepted participants. The owner is the only human participant. The agent (backend automation) acts on the owner's behalf and reports state; supported job sources and ATS platforms (LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, Workday, Greenhouse, Lever) and Gmail are provider-owned systems the owner authorizes and whose state the owner observes. Recruiters and HR contacts are outbound recipients whose information is surfaced with source and verification status; they are not product users.

Observable success. Applications are prepared automatically but only submitted after explicit approval; emails are only sent after approval; tracking is accurate with no duplicate or unconfirmed submissions; the owner can see at a glance what the agent actually knows versus what still needs them.

Source-backed constraints. Never invent missing information; never invent email addresses; never bypass CAPTCHA, MFA, anti-bot protection, authentication restrictions, or website security controls; never submit or send without approval; never mark an application as submitted without confirmation; prevent duplicate applications.

5. Core User Flows

Flow 1 — First-time enrollment and entry (Job Seeker (Owner))

1. The owner opens the Landing page anonymously and reads what JobPilot AI does, its audience, and its automated-but-user-controlled workflow, including the safety statement that it never bypasses CAPTCHA/MFA/anti-bot/security controls and never submits without approval.
2. The owner selects the primary CTA or the Sign Up path and lands on Sign Up.
3. The owner establishes their application identity on Sign Up. On success, they enter the protected console; on a validation or duplicate-identity error, the error is shown inline and they correct it or switch to Login.
4. The owner arrives at the Dashboard with no data yet: metric bands show explicit zero states and charts render empty on the page ground.
5. Next step: the owner opens Career Profile to enter verified information.

Flow 2 — Returning verification (Job Seeker (Owner))

1. The owner opens Login anonymously.
2. The owner verifies their identity. On success they enter the protected console; on invalid credentials an inline error is shown without revealing which field is wrong.
3. The owner lands on the Dashboard, which reflects their durable state: metrics, charts, connection health, and the agent status strip.
4. Next step: the owner reviews the "waiting for approval" band and opens the Approval Queue, or continues any other work.

Flow 3 — Building the verified career profile (Job Seeker (Owner))

1. From the Dashboard, the owner opens Career Profile.
2. The owner adds and verifies personal details, experience, education, skills and tools, certifications, preferred roles and locations, salary expectations, notice period, work authorization, visa sponsorship requirement, and uploads the master resume.
3. Fields the owner has not supplied remain visibly unset; the system never invents them.
4. If a save fails, the entered value is preserved and the failure is reported inline; the owner retries or discards.
5. Observable result: the profile shows verified facts with verification indicators and explicit unset states.
6. Next step: the owner connects portals and Gmail, or runs a job search.

Flow 4 — Connecting job portals and Gmail (Job Seeker (Owner))

1. From the Dashboard left rail, the owner opens Connections.
2. The owner selects a supported job portal and is handed to the provider's authorization flow (OAuth, API, or permitted integration). No password or API secret is entered into or exposed by the frontend.
3. On success, the connection band shows connection status, last sync, profile status, last search, applications prepared, and applications submitted; machine-confirmed connections use the lime truth color.
4. If authorization is denied or expires, the band shows an explicit error with a reconnect action; the owner reconnects.
5. The owner opens Email Inbox and connects Gmail the same way.
6. Observable result: connected portals and Gmail show live status and activity.
7. Next step: the owner configures Monitoring.

Flow 5 — Configuring scheduled monitoring (Job Seeker (Owner))

1. From the Dashboard left rail, the owner opens Monitoring.
2. The owner creates a scheduled search, chooses the interval — every hour, every 3 hours, every 6 hours, or daily — and selects the job portals and company career pages to monitor.
3. The owner enables the schedule. The console shows the next run and a monospace cron-style expression.
4. If backend scheduling is not configured, the console states explicitly that monitoring while the dashboard is closed requires backend scheduling to be configured; the owner configures it or runs a search on demand.
5. Observable result: the schedule runs even when the dashboard is closed, when backend scheduling is configured, and results appear in Jobs.
6. Next step: the owner reviews results in Jobs.

Flow 6 — Searching and filtering jobs (Job Seeker (Owner))

1. From the Dashboard or the left rail, the owner opens Jobs.
2. The owner runs a search across supported sources — LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, and ATS platforms such as Workday, Greenhouse, and Lever — or asks the floating AI chat to find relevant jobs or search company career pages.
3. The owner applies filters for role, country, experience, salary, date posted, remote/hybrid/onsite, and visa sponsorship.
4. Results render in a dense table with 11px caps headers and right-aligned tabular numeric columns, each row identifying its source. If one source fails, its failure is reported and results from other sources remain usable.
5. If the filters produce no results, an explicit empty state with a reset action is shown.
6. Observable result: a filtered result set the owner can act on.
7. Next step: the owner opens a job into Match Review.

Flow 7 — Reviewing match and tailoring the resume (Job Seeker (Owner))

1. The owner opens a job in Match Review and sees the match score against their verified profile facts, with the evidence panel showing which verified facts produced the score.
2. If scoring cannot complete, an explicit unscored state is shown rather than a fabricated score; the owner re-runs scoring or returns to Jobs.
3. The owner accepts the match and proceeds to Resume Studio.
4. In Resume Studio, the owner generates a job-specific ATS-friendly resume built only from verified information. If verified information is insufficient, generation stops and asks for the missing facts.
5. The owner edits the resume before use, creates a cover letter, compares original vs customized, selects a version from history, and downloads as PDF or DOCX.
6. If generation or export fails, the last good version is preserved and the owner retries or reverts.
7. Observable result: a tailored resume and cover letter tied to that job.
8. Next step: the owner sends the job to Application Prep.

Flow 8 — Preparing an application with agent automation (Job Seeker (Owner))

1. The owner opens Application Prep for the selected job.
2. The agent opens the supported job portal, fills known information, uploads the correct resume, answers questions using the verified profile, and continues across application pages. The agent status strip shows a tangerine progress rule and a streaming monospace action log (for example, "Workday · page 2/4 · 6 answers from profile").
3. If the agent encounters an unknown question, it stops that application and asks the owner. The owner answers, and preparation resumes from the saved step.
4. If a login, CAPTCHA, MFA, or manual verification is required, the agent stops and asks the owner to complete it manually. Progress is saved while the owner completes the step, and the agent resumes afterward.
5. If the website does not support automation or automation otherwise cannot continue, progress is saved and Open & Continue is offered. The owner selects Open & Continue to resume from the saved step.
6. If the job is already applied to, the duplicate is detected, the application is stopped, and the existing record is shown.
7. Observable result: a fully prepared application, or a saved interrupted application with Open & Continue.
8. Next step: the prepared application moves to the Approval Queue.

Flow 9 — Approving, editing, or rejecting a submission (Job Seeker (Owner))

1. The owner opens the Approval Queue (or arrives from the Dashboard's "waiting for approval" band).
2. The owner reviews the evidence pane: company and job, application URL, resume, cover letter, personal information, application questions and answers, salary, visa/work authorization, and attachments. A monospace line above the pinned control bar lists exactly what will be sent.
3. The owner chooses Edit, Reject, or Approve & Submit from the pinned full-width bottom bar, which never scrolls away.
4. If the owner chooses Edit, they change the prepared content and return to the decision.
5. If the owner chooses Reject, the application is not submitted and the record reflects the rejection.
6. If the owner chooses Approve & Submit, only then is the application submitted. On success it is marked submitted with confirmation; on failure the prepared application is preserved, is not marked submitted, and the owner retries, edits, or rejects.
7. Observable result: a submitted application with confirmed status, or a rejected/edited application.
8. Next step: the owner tracks the result in Applications.

Flow 10 — Monitoring replies and preparing drafts (Job Seeker (Owner))

1. The owner opens Email Inbox and reviews Gmail-derived messages categorized as recruiter emails, application confirmations, assessments, interviews, rejections, offers, and follow-ups.
2. If Gmail authorization has expired or is unavailable, an explicit state with a reconnect action is shown; the owner reconnects and refreshes.
3. The owner opens a message and hands it to Reply Drafts.
4. In Reply Drafts, the owner reviews the prepared reply, edits it, and either approves sending or discards it. The email is never sent without approval.
5. If sending fails, the draft is preserved and not marked sent; the owner retries, edits, or discards.
6. Observable result: a sent reply after approval, or a discarded draft.
7. Next step: the owner updates the related application in Applications.

Flow 11 — Finding recruiters (Job Seeker (Owner))

1. The owner opens Recruiters.
2. The owner searches for legitimate publicly available recruiter/HR information. Results show name, role, company, email, source, and verification status; machine-verified records use the lime truth color.
3. Email addresses are never invented. If no legitimate record is found, the result is empty rather than fabricated.
4. If the lookup fails, the failure is shown inline and the owner retries or refines the query.
5. The owner links a recruiter to an application.
6. Observable result: a sourced, verification-status-labeled recruiter record linked to an application.
7. Next step: the owner prepares a follow-up via the floating AI chat or Reply Drafts.

Flow 12 — Tracking applications and exporting (Job Seeker (Owner))

1. The owner opens Applications and browses durable records containing company, job title, posting date, applied date, country/city, job link, job description, salary, INR salary conversion, visa sponsorship, work authorization, match score, resume used, recruiter, follow-up date, application status, and notes.
2. The owner edits status, follow-up date, recruiter, and notes. A failed edit preserves the prior value.
3. The owner exports to a real .xlsx file with filters, frozen headers, clickable job links, proper date/currency formatting, and separate sheets where useful.
4. If the export fails, the failure is reported without altering the records and the owner retries.
5. Observable result: an up-to-date tracker and a usable .xlsx file.
6. Next step: the owner returns to the Dashboard to read the updated pipeline.

Flow 13 — Reading the dashboard (Job Seeker (Owner))

1. The owner opens the Dashboard.
2. The owner reads jobs found today, strong matches, applications prepared, waiting for approval, applications submitted, recruiter replies, interviews, rejections, offers, and follow-ups due, rendered as ruled metric bands with 11px caps labels and right-aligned tabular numerals, with headline numerals in Space Grotesk counting up once on entry (300ms, linear).
3. The owner reads charts for applications by country, role, source, status, and time, drawn flat on the page ground with no chart junk. A chart with no data renders an explicit empty state.
4. If a metric cannot be computed, it is shown as unavailable rather than fabricated; the owner retries that band while other bands remain usable.
5. The owner opens the relevant page from a metric — for example, the Approval Queue from "waiting for approval".
6. Observable result: an accurate read of the pipeline and the agent's state.
7. Next step: the owner acts on whatever needs them.

Flow 14 — Driving the agent from any page (Job Seeker (Owner))

1. From any page, the owner opens the floating AI chat button.
2. The owner asks the agent to find relevant jobs, search company career pages, check visa sponsorship, customize resumes, prepare applications, check Gmail for recruiter replies, update application tracking, or prepare follow-up emails.
3. The agent performs the action and reports the result; if it cannot, it states why and what is needed.
4. Observable result: the requested action is performed or an explicit reason is given.
5. Next step: the owner continues in the relevant page.

6. Visuals Colors and Theme

The creative direction is authoritative. Muse: Rasmus Andersson. Headline: Systematic product craft with an opinion — graphite ground, tangerine signal, tabular numerals as ornament. This is a power-user automation console: dense, stateful, approval-gated software — a control room, not a marketing site. It must never feel like a consumer lifestyle app, and it must never look like a Bootstrap admin template.

Color tokens (dark mode, default console surface)

Rules: no blue anywhere in the system; no gradients; colour is never used for large fills except one 100%-width tangerine band on the hero. Tangerine does structural work — the active nav rule, the primary CTA, the "waiting for approval" badge, the agent's live cursor. Acid lime is reserved exclusively for machine-confirmed truth — verified recruiter emails, submitted applications, connected portals — so a glance tells the owner what the agent actually knows versus what it merely claims. Elevation is expressed by a lighter surface, never by blur or shadow.

Typography

• Headings: Space Grotesk 500/600, tight tracking (−0.02em to −0.04em), sentence case for section titles; ALL-CAPS only for 11px micro-labels with 0.14em letterspacing ("APPLICATIONS PREPARED", "LAST SYNC").
• Headline numerals: Space Grotesk at huge sizes so metrics read as display type, not dashboard chrome.
• Body and controls: Inter Tight 400/500 at 13–15px with −0.01em tracking. Never plain Inter, never Roboto.
• Monospace voice: JetBrains Mono at 12–13px for job IDs, URLs, ATS keys, cron expressions, and audit lines.
• Scale: 1.25 modular on a 4/8pt rhythm — 12 / 13 / 15 / 18 / 22 / 28 / 40 / 64 / clamp(56px, 9vw, 128px) for the hero metric.
• Numerals: tabular everywhere (font-variant-numeric: tabular-nums).

Shape language

Sharp and engineered. 2px radii on inputs and buttons, 4px on panels, 0px on table rows and section bands — nothing pill-shaped, nothing soft. 1px hairline borders (#2A2D31) do all the separating. A recurring 8px square "status stud" (filled, half-filled, hollow) replaces conventional status dots and is the system's one decorative-but-functional motif.

Layout

A fixed 232px left rail (icon + label nav, connection health at the bottom with live sync timestamps) against a full-width content plane with a 1280px max reading width and 24/40px gutters. Content is built from ruled bands rather than cards: full-width rows separated by hairlines, aligned label/value pairs, and dense tables where column headers are 11px caps and numeric columns are right-aligned on tabular numerals. The dashboard is a 12-column grid of metric bands, not a card grid; charts are flat, single-hue-plus-accent, drawn on the page ground with no chart junk. Approval screens use a two-pane split: evidence on the left, the Edit | Reject | Approve & Submit control bar pinned full-width at the bottom, always visible, never scrolled away.

Imagery

The interface is the imagery: rendered tables, schematic pipeline diagrams (Find → Match → Tailor → Approve → Submit → Track drawn as a ruled horizontal band with the active stage in tangerine), monospace code and JSON answer previews, and a small set of 1px-stroke pictograms for portals and ATS platforms. No stock photography, no people, no illustration, no 3D, no gradient blobs. Where a real artefact is needed — a resume diff, a recruiter email, an application form — it is shown as a faithful document panel with hairline rules and tabular metadata.

7. Signature Design Concept

The control-room header. The public entry (Landing) is not a marketing hero; it is an instrument panel whose largest element is a number.

• Full-bleed graphite #141517 ground.
• A 100%-viewport-width tangerine #FF7A2F band, 6px tall, pinned across the very top as the "agent is live" rule.
• Beneath it, left-aligned and bleeding to the right edge, an oversized Space Grotesk metric — "47 JOBS FOUND TODAY" at clamp(56px, 9vw, 128px), tabular numerals, tracking −0.04em.
• Directly under it, a second line at 22px in muted #7C8087: "12 strong matches · 5 prepared · 3 awaiting your approval".
• To the right, occupying the remaining columns at desktop and dropping below the headline at 768px and 375px, sits the live agent status panel: a bordered surface with a monospace action log streaming line by line, a tangerine progress rule, and the single primary CTA "Review 3 approvals" as a solid tangerine rectangle with 2px radius.
• No centred headline, no subtext-then-button stack, no gradient, no illustration.

The concept recomposes only accepted content and controls: the workflow stages, the agent's activity, the approval count, and the entry CTA. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the live agent status panel — a bordered surface carrying a monospace action log and a tangerine progress rule — set against the oversized tabular metric.
• Input → transformation → outcome thesis: the agent's real activity (searching sources, filling application pages, checking Gmail) streams into the monospace log line by line; the tangerine progress rule advances along the top of the panel as the current action proceeds; the outcome is a readable, auditable transcript of what the agent is doing right now, with the single primary CTA to review approvals. Only accepted behaviour is shown — no invented agent actions.
• Motion vocabulary: fast and functional — 120–200ms cubic-bezier(0.2, 0, 0, 1) on state changes, no bounce, no lift. Numerals count up once when a metric enters view (300ms, linear). Nothing loops, nothing floats, nothing parallaxes; the only continuous motion is the status rule while the agent is genuinely running.
• Composed first frame: graphite ground; 6px full-width tangerine rule at the very top; the oversized metric left-aligned and bleeding right; the muted summary line beneath it; the agent status panel to the right with a static progress rule and the first monospace log line already rendered; the solid tangerine CTA inside the panel.
• Reduced-motion state: the progress rule is static, the monospace log renders as a complete list of the latest actions rather than streaming, and numerals appear at their final values without counting up. All readable text and controls remain whole and inside the viewport at 375px, 768px, and 1280px.

9. Non-Functional Requirements

• NFR-1 — No security-control bypass (explicit). The system must never bypass CAPTCHA, MFA, anti-bot protection, authentication restrictions, or website security controls. Rationale: explicit safety constraint; when such a control is encountered the agent stops and asks the owner to complete it manually.
• NFR-2 — No secret exposure in frontend code (explicit). Passwords and API secrets must never be exposed in frontend code; job portal and Gmail connections use OAuth, APIs, or permitted integrations. Rationale: explicit security constraint.
• NFR-3 — Approval gating (explicit). No application may be submitted and no email may be sent without explicit owner approval. Rationale: explicit hard constraint and the product's main rule.
• NFR-4 — Submission truthfulness (explicit). An application must never be marked as submitted without confirmation. Rationale: explicit constraint; the tracker must reflect reality.
• NFR-5 — Duplicate prevention (explicit). The system must prevent duplicate applications. Rationale: explicit constraint.
• NFR-6 — No fabrication (explicit). The system must never invent missing information, and must never invent email addresses. Rationale: explicit constraints; resume customization uses only verified information and Recruiter Finder shows only legitimate publicly available information.
• NFR-7 — Background scheduling (explicit). Continuous monitoring must run even when the dashboard is closed, when backend scheduling is configured. Rationale: explicit constraint; the qualifier is preserved — monitoring while the dashboard is closed depends on backend scheduling being configured.
• NFR-8 — Progress durability (explicit). When automation cannot continue, progress must be saved and an Open & Continue action provided. Rationale: explicit constraint; no prepared work is lost.
• NFR-9 — Real .xlsx output (explicit). Excel export must produce a real .xlsx file with filters, frozen headers, clickable job links, proper date/currency formatting, and separate sheets where useful. Rationale: explicit requirement.
• NFR-10 — Readable text and controls at every viewport (creative direction). Headlines, wordmarks, labels, numbers, card text, and controls must 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, and no other element may cover any part of them. Rationale: authoritative creative direction; this rule takes precedence for readable text and controls.
• NFR-11 — Reduced-motion compliance (creative direction). With prefers-reduced-motion, motion stops and whole items are shown: they wrap into rows, or sit in a horizontally scrollable row (overflow-x: auto) whose further items are reached by scrolling. Rationale: authoritative creative direction.
• NFR-12 — Tabular numerals and alignment (creative direction). Numerals are tabular everywhere, and numeric table columns are right-aligned. Rationale: authoritative creative direction; dense numeric records must align.

10. Tech Stack

• Frontend: React web application. Rationale: the product is a working web application with a dense, stateful console; React is the appropriate first-party web UI technology. [Default — not specified by user]
• Backend: Python with FastAPI. Rationale: the product requires backend automation, scheduled jobs, provider integrations, and document generation; FastAPI is the appropriate Python service framework. [Default — not specified by user]
• Storage: A relational database for durable career profile, application, resume version, connection, schedule, and message state, plus object storage for generated resume/cover-letter files and .xlsx exports. [Default — not specified by user]
• Scheduling: Backend scheduling configured to run recurring searches at every hour, every 3 hours, every 6 hours, or daily, and to continue while the dashboard is closed. Rationale: explicit requirement that monitoring runs when the dashboard is closed, when backend scheduling is configured.
• Integrations: OAuth, APIs, or permitted integrations for supported job portals (LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, Workday, Greenhouse, Lever) and Gmail. Rationale: explicit requirement; passwords and API secrets are never exposed in frontend code.
• Document generation: PDF and DOCX resume/cover-letter generation, and real .xlsx export with filters, frozen headers, clickable job links, proper date/currency formatting, and separate sheets where useful. Rationale: explicit requirements.
• Containerization: Docker and docker-compose for local and deployment packaging. [Default — not specified by user]

11. Assumptions and Constraints

Assumptions

• A-1: The Job Seeker (Owner) is the sole active human user; all protected state belongs to that single owner. Source: Planning Scope persona catalog.
• A-2: Application-owned identity is required so the owner's durable career, application, integration, and approval state can be privately owned and resumed; enrollment is self-service and returning access is verified. Provenance: required_inference.
• A-3: Backend scheduling must be configured for monitoring to run while the dashboard is closed; when it is not configured, the console states this explicitly. Source: explicit qualifier.
• A-4: Supported job portals and Gmail are provider-owned systems reached through OAuth, APIs, or permitted integrations; the product does not own their authorization. Source: explicit requirement.
• A-5: Some supported websites do not support automation; in those cases the agent stops and asks the owner. Source: explicit requirement.
• A-6: Recruiter and HR information is limited to legitimate publicly available sources and is shown with its source and verification status. Source: explicit requirement.

Constraints

• C-1: Never submit an application automatically; only submit after the owner selects Approve & Submit.
• C-2: Never send emails without approval.
• C-3: Never invent missing information; resume customization must use only verified information.
• C-4: Never invent email addresses in Recruiter Finder.
• C-5: Never bypass CAPTCHA, MFA, anti-bot protection, authentication restrictions, or website security controls.
• C-6: Never mark an application as submitted without confirmation.
• C-7: Prevent duplicate applications.
• C-8: Never expose passwords or API secrets in frontend code; use OAuth, APIs, or permitted integrations for job portal connections.
• C-9: The AI must interrupt the owner only for missing or uncertain information, login/CAPTCHA/MFA/manual verification, websites that do not support automation, and final application approval.
• C-10: Continuous monitoring runs even when the dashboard is closed only when backend scheduling is configured.
• C-11: For unknown application questions, stop that application and ask the owner.
• C-12: The floating AI chat button must be present on every page.
• C-13: The main rule governs all behaviour: the AI searches, prepares, and manages everything possible automatically; the owner controls what is finally submitted or sent.

12. Glossary

• Job Seeker (Owner): The single active human user who owns the end-to-end workflow and holds the trigger on submissions and sends.
• Agent: The backend automation that searches, matches, tailors, prepares, monitors, and reports, acting on the owner's behalf within the stated constraints.
• Approval Queue: The surface where prepared submissions are reviewed and decided with Edit | Reject | Approve & Submit.
• Approve & Submit: The only action that causes an application to be submitted.
• Open & Continue: The action offered when automation cannot continue, which resumes an application from its saved step.
• Match score: The fit evaluation of a job against the owner's verified profile facts.
• Master resume: The owner's verified source resume from which job-specific versions are derived.
• ATS: Applicant Tracking System; supported platforms include Workday, Greenhouse, and Lever.
• Supported sources: LinkedIn, Naukri, Indeed, Glassdoor, Foundit, Wellfound, company career pages, recruitment agencies, and ATS platforms such as Workday, Greenhouse, and Lever.
• Verified information: Profile facts the owner has supplied and confirmed; the only material permitted in resumes, answers, and applications.
• Machine-confirmed truth: Facts the agent has actually verified (verified recruiter email, submitted application, connected portal), rendered in acid lime.
• Status stud: The recurring 8px square status motif (filled, half-filled, hollow) that replaces conventional status dots.
• Agent status strip: The tangerine progress rule paired with a streaming monospace action log that makes automation readable and auditable.
• INR salary conversion: The tracked conversion of a job's salary into Indian rupees on the application record.
• Follow-up: A tracked future contact date on an application, and the prepared follow-up email associated with it.