System Requirements Document for project-0d888692

1. Introduction

Invoice Nudge is a micro SaaS product for freelancers, small agencies, consultants, service businesses, and bookkeepers who manage client receivables. It exists to solve one core problem: chasing unpaid invoices without manual effort.

The product automatically sends polite invoice reminders and collections follow-ups before and after an invoice's due date, and stops the sequence the moment an invoice is marked paid. Users add invoices manually or import them from CSV or Google Sheets, configure reminder timing, tone, and escalation levels, and monitor overdue amount, recovered amount, and next reminders from a simple dashboard. Every outgoing message, reply, and status update is logged.

The audience is small, non-corporate service businesses — people who feel a low-grade social dread about chasing money and want calm, reliable automation rather than an enterprise billing suite. The interface must be simple, clean, and non-corporate, and the default reminder language must never be aggressive.

This document specifies the current MVP scope, its pages, its personas, its functional and non-functional requirements, and its core user flows. Optional upgrades named in the source (SMS, WhatsApp, late fees, promise-to-pay, payment links, client portal, multi-user team access, AI tone variations, and Stripe/Razorpay/QuickBooks/Xero integrations) are explicitly out of the current MVP and are recorded in the future section.

2. System Overview

Invoice Nudge is a multi-tenant web SaaS. Each user owns a private invoice book, a reminder configuration, a set of editable reminder templates, and a durable activity history. A background scheduler evaluates invoices against the configured reminder sequence in the correct timezone and dispatches reminder emails to clients; the sequence halts automatically when an invoice's payment status becomes paid.

Actors

• Freelancer / Consultant — solo service provider who adds or imports invoices, customizes tone and timing, and relies on automatic pre-due and post-due reminders that stop once payment is received.
• Small agency / service business operator — runs a small team's receivables: a larger invoice book, escalation levels and reminder sequences, and monitoring of next reminders and recovered revenue.
• Bookkeeper managing client receivables — maintains invoice records and payment status on behalf of client businesses, imports invoices, marks invoices paid so reminders stop, and reviews the activity log of every reminder, reply, and status update.
• Client (invoice recipient) — an outbound-only email recipient. The client is not a product user and has no first-party surface in the current MVP; the client portal is an explicitly deferred optional upgrade.
• Reminder scheduler / email delivery service — system and provider actors that execute configured reminders and deliver email.

Current delivery

A first-party web application with a public landing page, self-service sign-up and login, and a protected workspace containing the dashboard, invoice book, invoice creation and detail workspaces, CSV import, Google Sheets integration management, reminder settings, templates, and activity log. Background jobs run the reminder scheduler and email dispatch.

Narrow exclusions

The following are explicitly not part of the current MVP: SMS reminders, WhatsApp reminders, late fee calculation, promise-to-pay tracking, payment links, client portal, multi-user team access, AI-generated reminder tone variations, and integrations with Stripe, Razorpay, QuickBooks, and Xero.

2a. Product Interpretation and Delivery Boundary

Invoice Nudge is delivered as a first-party web application. The public entry is the Landing page, which explains the product, its target users, and automated unpaid-invoice follow-up before sign-in. Because the product must keep a durable, private invoice book, reminder configuration, and audit history bound to the correct person, the application owns identity: Sign Up establishes a new account and Login verifies a returning user. Both are anonymously reachable; the protected workspace is not.

Everything that operates on a user's own receivables — the dashboard, the invoice book, invoice creation and detail, CSV import, Google Sheets integration management, reminder settings, templates, and the activity log — requires a signed-in session. There is no differentiated permission model in the current MVP: each signed-in user works within their own account's records. Multi-user team access is an explicitly deferred upgrade, so no role-based visibility or shared-state permission control is specified.

Reminder execution and email delivery are background responsibilities. The scheduler runs outside the user's browser session, evaluates each invoice against the configured sequence in the correct timezone, dispatches email through the configured provider, and writes an audit record for every outgoing message. The stop-on-paid rule is enforced by that background process, not by the user's presence in the app.

The client who receives a reminder email is an outbound recipient only. The current MVP gives the client no surface, no account, and no interaction inside the product; the client portal is deferred.

2c. Page Content and Component Coverage

Landing

• Information / state: Public, unauthenticated. Explains Invoice Nudge, the core problem it solves (chasing unpaid invoices without manual effort), the target users (freelancers, small agencies, consultants, service businesses, bookkeepers managing client receivables), the automated pre-due and post-due reminder behavior, the stop-on-paid rule, and the dashboard outcomes (overdue amount, recovered amount, next reminders).
• Primary actions: Navigate to Sign Up; navigate to Login.
• Supporting actions: Read the reminder sequence explanation (T-3 gentle, due-date polite, T+3 follow-up, T+7 firmer, T+14 final or escalation); read the product rules (never send after payment, no aggressive language by default, all templates editable, timezone-based scheduling, audit logs for every outgoing message).
• Domain entities: Product description, reminder sequence steps, product rules, target-user descriptions.
• Component responsibilities: Split hero with a paper half (a rendered reminder email card) and a dark engine half (the five-tick reminder timeline with an active tick and a struck-through stopped state); a seam rule separating the halves; a reminder-timeline component; a paper email card component; schematic diagrams for stop-on-paid and timezone offset; a CSV/Sheets column-map diagram; primary CTA to Sign Up and secondary link to Login.
• States: Loading — static content, no data fetch required. Empty — not applicable. Success — page renders fully. Error — if any dynamic element fails, the static copy and both navigation actions remain usable. Recovery — navigation actions are always available regardless of decorative element failure.

Login

• Information / state: Anonymous access surface for returning users. Collects the credentials required to verify an existing account and reach the protected workspace.
• Primary actions: Submit credentials to sign in; navigate to Sign Up if the visitor has no account.
• Supporting actions: Recover from an invalid-credential error by correcting input and resubmitting.
• Domain entities: User identity, session.
• Component responsibilities: Credential form; submit control; link to Sign Up; inline validation and error messaging.
• States: Loading — submit control shows an in-progress state while verification runs. Empty — not applicable. Success — session established and the user is taken into the protected workspace. Error — invalid credentials or verification failure shows a clear message and preserves entered input for correction. Recovery — the user can retry immediately or switch to Sign Up.

Sign Up

• Information / state: Anonymous access surface for self-starting users. Establishes a new account so the user can own a private invoice book, reminder configuration, and activity history.
• Primary actions: Submit enrollment details to create the account; navigate to Login if the visitor already has an account.
• Supporting actions: Correct validation errors inline and resubmit.
• Domain entities: User identity, account, session.
• Component responsibilities: Enrollment form; submit control; link to Login; inline validation and error messaging.
• States: Loading — submit control shows an in-progress state while the account is created. Empty — not applicable. Success — account created, session established, and the user enters the protected workspace with an empty invoice book. Error — validation failure or enrollment failure shows a clear message and preserves entered input. Recovery — the user can correct and resubmit, or switch to Login.

Dashboard

• Information / state: Protected. Summarizes the user's receivables position: overdue amount, recovered amount, and next reminders. Reflects the current state of the user's invoice book and reminder schedule.
• Primary actions: Open an invoice from the next-reminders list; navigate to Invoices; navigate to New Invoice.
• Supporting actions: Navigate to CSV Import, Integrations, Reminder Settings, Templates, and Activity.
• Domain entities: Invoice, payment status, reminder stage, reminder schedule, recovered amount, overdue amount.
• Component responsibilities: Overdue-amount summary; recovered-amount summary; next-reminders list with invoice identity, client, amount, and scheduled send time; navigation rail to the other protected pages.
• States: Loading — summaries and next-reminders list show a loading state while data is fetched. Empty — a new account with no invoices shows an empty state directing the user to add an invoice manually or import via CSV or Google Sheets. Success — overdue amount, recovered amount, and next reminders render with current values. Error — if summary data fails to load, a clear error is shown with a retry action and navigation remains usable. Recovery — retry reloads the summaries; the user can still reach Invoices and New Invoice.

Invoices

• Information / state: Protected. The user's durable invoice book and payment-status records. Each invoice carries client name, email, amount, due date, status, reminder stage, and notes.
• Primary actions: Open an invoice to its detail workspace; start a new invoice; mark an invoice paid.
• Supporting actions: Filter or scan by status and reminder stage; navigate to CSV Import to add records in bulk.
• Domain entities: Invoice (client name, client email, amount, due date, status, reminder stage, notes), payment status.
• Component responsibilities: Invoice list with client name, amount, due date, status, and reminder stage; row-level status chip that reveals the next scheduled send; action to open detail; action to mark paid; action to start a new invoice.
• States: Loading — list shows a loading state while records are fetched. Empty — no invoices yet shows an empty state with actions to add manually or import. Success — invoices render with current status and reminder stage. Error — a failed load shows a clear error with retry. Recovery — retry reloads the list; the user can still create a new invoice.

New Invoice

• Information / state: Protected. Focused workspace for manually adding one invoice to the user's book.
• Primary actions: Enter client name, client email, amount, due date, status, reminder stage, and notes; save the invoice.
• Supporting actions: Cancel and return to the invoice book without saving.
• Domain entities: Invoice (client name, client email, amount, due date, status, reminder stage, notes).
• Component responsibilities: Invoice form with the named fields; save control; cancel control; inline field validation.
• States: Loading — save control shows an in-progress state while the record is written. Empty — the form starts blank. Success — the invoice is saved and appears in the invoice book with its reminder stage and schedule. Error — validation failure or save failure shows a clear message and preserves entered values. Recovery — the user corrects and resaves, or cancels without creating a record.

Invoice Details

• Information / state: Protected. Focused workspace for one existing invoice: its client name, email, amount, due date, status, reminder stage, and notes, plus its reminder position and history.
• Primary actions: Review the invoice; edit its fields; delete the invoice; mark the invoice paid.
• Supporting actions: Review the reminder timeline for this invoice, including sent steps and the next scheduled step; review this invoice's entries in the activity history.
• Domain entities: Invoice, payment status, reminder stage, reminder timeline, activity record.
• Component responsibilities: Invoice field display and edit controls; mark-paid control; delete control with confirmation; reminder timeline component showing the five sequence steps with the active step and any stopped state; per-invoice activity entries.
• States: Loading — invoice fields and timeline show a loading state. Empty — not applicable for an existing invoice; a deleted or missing invoice shows a not-found state with a route back to the invoice book. Success — fields, timeline, and history render; marking paid collapses the timeline into a stopped state with the paid date. Error — a failed save, delete, or mark-paid shows a clear message and leaves the prior state intact. Recovery — the user retries the action; a failed mark-paid leaves reminders governed by the previously persisted status until the action succeeds.

CSV Import

• Information / state: Protected. Imports invoice records from CSV files into the user's receivables records.
• Primary actions: Select or provide a CSV file; map its columns to invoice fields; confirm the import.
• Supporting actions: Review the column mapping before confirming; correct a mapping and re-run.
• Domain entities: CSV file, column mapping, invoice (client name, client email, amount, due date, status, reminder stage, notes).
• Component responsibilities: File selection; column-map view showing sheet headers mapped to schema fields; import confirmation; import result summary.
• States: Loading — parsing and import show progress. Empty — before a file is chosen, the page shows the expected columns and the mapping affordance. Success — imported invoices appear in the invoice book with their reminder stages. Error — unparseable files, unmapped required columns, or row-level failures are reported clearly with the affected rows identified. Recovery — the user corrects the mapping or file and re-runs the import.

Integrations

• Information / state: Protected. Connects and manages Google Sheets synchronization for invoice records.
• Primary actions: Connect a Google Sheets source; configure which sheet supplies invoice records; run or refresh a sync.
• Supporting actions: Review the last sync result; disconnect the source.
• Domain entities: Google Sheets connection, sheet, column mapping, invoice, sync result.
• Component responsibilities: Connection control; sheet and column selection; sync trigger; last-sync status display.
• States: Loading — connection and sync operations show progress. Empty — with no connection, the page explains what syncing provides and offers the connect action. Success — a completed sync reports how many invoice records were created or updated. Error — authorization failure, unavailable sheet, or mapping failure is reported clearly. Recovery — the user reconnects, corrects the sheet or mapping, and re-runs the sync.

Reminder Settings

• Information / state: Protected. Configures reminder timing, timezone behavior, message tone, and escalation levels for the pre-due and post-due sequence.
• Primary actions: Set the reminder sequence steps and their offsets (T-3 gentle, due date polite, T+3 follow-up, T+7 firmer, T+14 final or escalation); set the timezone used for scheduling; set message tone; set escalation levels; save the configuration.
• Supporting actions: Review how the configured sequence will fire for a given due date; navigate to Templates to edit the messages those steps send.
• Domain entities: Reminder sequence, reminder step, offset, timezone, tone, escalation level.
• Component responsibilities: Sequence editor with the five named steps and their offsets; timezone selector; tone control; escalation-level control; save control; sequence preview.
• States: Loading — current configuration loads into the editor. Empty — a new account shows the default sequence (T-3, due date, T+3, T+7, T+14) ready to adjust. Success — saved configuration governs subsequent scheduling. Error — invalid offsets or a failed save show a clear message and preserve the edited values. Recovery — the user corrects and resaves; the previously saved configuration remains in effect until a save succeeds.

Templates

• Information / state: Protected. The reminder messages used by the configured sequence. Every template is editable.
• Primary actions: Edit any reminder template; save changes.
• Supporting actions: Preview a template as the client will read it, including the sequence step and timezone footer; revert an edit before saving.
• Domain entities: Reminder template, sequence step, tone, message body.
• Component responsibilities: Template list keyed to sequence steps; template editor; paper-card preview showing the rendered message with its sequence step and timezone footer; save control.
• States: Loading — templates load into the editor. Empty — if a step has no template, the page offers the default polite wording for that step. Success — saved templates are used by subsequent reminder sends. Error — a failed save shows a clear message and preserves the edited text. Recovery — the user retries the save; the previously saved template remains in use until a save succeeds.

Activity

• Information / state: Protected. The durable history of reminders, replies, status updates, and outgoing-message audit records.
• Primary actions: Review the activity history; open the related invoice.
• Supporting actions: Scan entries by invoice, by event type, and by time.
• Domain entities: Activity record (event type, invoice reference, timestamp, recipient, sequence step), reminder, reply, status update, audit record.
• Component responsibilities: Chronological activity list with event type, invoice reference, recipient, sequence step, and timestamp; link to the related invoice.
• States: Loading — history shows a loading state while records are fetched. Empty — no activity yet shows an empty state explaining that reminders, replies, and status updates will appear here. Success — entries render in order with their timestamps. Error — a failed load shows a clear error with retry. Recovery — retry reloads the history.

3. Functional Requirements

FR-1 — Automated reminder and collections follow-up (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have Invoice Nudge automatically send polite invoice reminders and collections follow-ups until payment is received, so that I no longer chase unpaid invoices manually.

• Trigger: an invoice exists with a due date and a configured reminder sequence.
• Observable result: reminders are dispatched at the configured sequence points before and after the due date.
• Failure/recovery: a failed dispatch is recorded and does not silently advance the sequence without an audit entry.
• Continuation: the sequence continues until the invoice is marked paid or the final step is reached.

FR-2 — Manual invoice entry (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should add invoices manually, so that new receivables enter the reminder pipeline without an import step.

• Trigger: the user opens New Invoice and submits the form.
• Observable result: the invoice is saved to the user's book and appears in Invoices and on the Dashboard.
• Failure/recovery: validation or save failure preserves entered values for correction.
• Continuation: the saved invoice is scheduled against the configured reminder sequence.

FR-3 — CSV import (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should import invoices via CSV, so that an existing receivables list can be brought in without retyping.

• Trigger: the user provides a CSV file and confirms a column mapping.
• Observable result: imported invoices appear in the invoice book with their fields populated.
• Failure/recovery: unparseable files, unmapped required columns, and row-level failures are reported with the affected rows identified so the user can correct and re-run.
• Continuation: imported invoices are scheduled against the configured reminder sequence.

FR-4 — Google Sheets sync (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should sync invoices from Google Sheets, so that a sheet I already maintain can feed the reminder pipeline.

• Trigger: the user connects a Google Sheets source and runs a sync.
• Observable result: invoice records are created or updated from the sheet, and the last-sync result is shown.
• Failure/recovery: authorization, availability, or mapping failures are reported clearly and the user can reconnect or correct the mapping and re-run.
• Continuation: synced invoices are scheduled against the configured reminder sequence.

FR-5 — Invoice fields (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have each invoice hold client name, email, amount, due date, status, reminder stage, and notes, so that the reminder pipeline has everything it needs to address and schedule a message.

• Trigger: invoice creation, import, sync, or edit.
• Observable result: all seven fields are stored and displayed on the invoice.
• Failure/recovery: missing or invalid required fields are reported at entry time.
• Continuation: the stored due date and reminder stage drive scheduling.

FR-6 — Invoice CRUD (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should create, read, update, and delete invoices, so that my receivables records stay accurate.

• Trigger: the user creates, opens, edits, or deletes an invoice.
• Observable result: the invoice book reflects the change.
• Failure/recovery: a failed save or delete shows a clear message and leaves the prior state intact.
• Continuation: the user retries or returns to the invoice book.

FR-7 — Pre-due and post-due reminders (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have the system send automated reminders before the due date and after the due date, so that clients are nudged both ahead of and past the deadline.

• Trigger: the scheduler reaches a configured offset relative to an invoice's due date.
• Observable result: the corresponding reminder email is dispatched to the invoice's client email.
• Failure/recovery: a failed send is recorded and surfaced in the activity history.
• Continuation: the remaining sequence steps continue on schedule.

FR-8 — Reminder sequence steps (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have the reminder sequence run as T-3 days gentle reminder, due date polite reminder, T+3 days follow-up, T+7 days firmer reminder, and T+14 days final reminder or escalation, so that follow-up escalates predictably.

• Trigger: the scheduler evaluates an unpaid invoice against each offset.
• Observable result: each step fires at its offset with the message configured for that step.
• Failure/recovery: a skipped or failed step is recorded in the activity history.
• Continuation: the sequence proceeds to the next step until paid or complete.

FR-9 — Stop reminders on payment (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have the reminder sequence stop automatically when an invoice is marked paid, so that a client who has paid is never reminded again.

• Trigger: the user marks an invoice paid.
• Observable result: no further reminders are sent for that invoice, and its reminder timeline shows a stopped state with the paid date.
• Failure/recovery: if the status change fails to persist, the prior status remains in effect and the user is told the change did not save.
• Continuation: the invoice remains in the book as paid and contributes to recovered amount.

FR-10 — Never send reminders after payment is received (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should be guaranteed that no reminder is sent after payment is received, so that paying clients are never chased.

• Trigger: any scheduler evaluation of an invoice whose payment status is paid.
• Observable result: the scheduler suppresses the send and records the suppression.
• Failure/recovery: if suppression cannot be confirmed, the send does not proceed.
• Continuation: the invoice stays out of the active reminder pipeline.

FR-11 — Log reminders, replies, and status updates (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have the system log every reminder, reply, and status update, so that I can see exactly what was sent and what changed.

• Trigger: a reminder is sent, a reply is received, or a status changes.
• Observable result: an entry appears in the activity history with its event type, invoice reference, and timestamp.
• Failure/recovery: a logging failure is surfaced rather than silently dropped.
• Continuation: the history remains the durable record for the account.

FR-12 — Audit logs for every outgoing message (explicit) As a Bookkeeper managing client receivables, I should have audit logs kept for every outgoing message, so that each client's receivables record is auditable.

• Trigger: any outgoing reminder email.
• Observable result: an audit record exists for that message, including its invoice reference, recipient, sequence step, and send time.
• Failure/recovery: a message that cannot be audited is not treated as successfully sent.
• Continuation: audit records accumulate in the activity history.

FR-13 — Customize tone, timing, and escalation (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should be able to customize message tone, timing, and escalation levels, so that follow-up matches how I want to speak to my clients.

• Trigger: the user edits Reminder Settings and saves.
• Observable result: the saved tone, timing, and escalation govern subsequent scheduling and message content.
• Failure/recovery: invalid offsets or a failed save show a clear message and preserve the edited values.
• Continuation: the previously saved configuration remains in effect until a save succeeds.

FR-14 — Edit all templates (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should be able to edit all reminder templates, so that every message a client receives is one I have approved.

• Trigger: the user edits a template and saves.
• Observable result: the saved template is used by subsequent sends for that sequence step.
• Failure/recovery: a failed save shows a clear message and preserves the edited text.
• Continuation: the previously saved template remains in use until a save succeeds.

FR-15 — Avoid aggressive language by default (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have the default reminder wording avoid aggressive language, so that collections follow-up stays polite without me having to rewrite it.

• Trigger: default templates are provisioned or a step has no user-authored template.
• Observable result: the default wording for every sequence step is polite and non-aggressive.
• Failure/recovery: not applicable to a content default.
• Continuation: the user may still edit any template.

FR-16 — Timezone-based scheduling (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have reminders scheduled according to timezone, so that a reminder lands at the intended local time rather than an arbitrary one.

• Trigger: the scheduler evaluates a step offset for an invoice.
• Observable result: the send time is computed in the configured timezone and shown with that timezone in the interface.
• Failure/recovery: an unresolved timezone prevents the send from being scheduled silently.
• Continuation: the resolved timezone applies to all subsequent steps.

FR-17 — Dashboard receivables summary (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should see a dashboard showing overdue amount, recovered amount, and next reminders, so that I know where my receivables stand at a glance.

• Trigger: the user opens the Dashboard.
• Observable result: overdue amount, recovered amount, and the next scheduled reminders are displayed.
• Failure/recovery: a failed load shows a clear error with retry.
• Continuation: the user can open an invoice or navigate to the invoice book.

FR-18 — Payment status tracking (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should track payment status per invoice, so that paid and unpaid invoices are distinguished and the reminder pipeline reflects reality.

• Trigger: the user sets or changes an invoice's status, including marking it paid.
• Observable result: the invoice's status is stored and displayed, and the reminder pipeline responds accordingly.
• Failure/recovery: a failed status change leaves the prior status in effect and is reported.
• Continuation: the updated status governs subsequent scheduling and dashboard totals.

FR-19 — User authentication (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should authenticate before reaching my invoice records, reminder configuration, and audit history, so that my receivables data stays private to me.

• Trigger: the user signs up or logs in.
• Observable result: a session is established and the protected workspace becomes reachable.
• Failure/recovery: invalid credentials or a failed enrollment show a clear message and preserve entered input.
• Continuation: the user retries or switches between Login and Sign Up.

FR-20 — Self-service enrollment (required_inference) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should be able to create my own account from Sign Up, so that I can start using Invoice Nudge without an invitation or provisioning step.

• Trigger: an unauthenticated visitor submits the Sign Up form.
• Observable result: an account is created, a session is established, and the user enters the protected workspace with an empty invoice book.
• Failure/recovery: validation or enrollment failure shows a clear message and preserves entered input.
• Continuation: the user proceeds to add or import invoices.

FR-21 — Returning verification (required_inference) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should be able to log in to my existing account, so that I can resume my invoice book, reminder configuration, and audit history.

• Trigger: a returning user submits the Login form.
• Observable result: the session is verified and the user's own records are reachable.
• Failure/recovery: invalid credentials show a clear message and preserve entered input.
• Continuation: the user resumes work in the protected workspace.

FR-22 — Background scheduling and delivery (required_inference) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have background scheduling and email delivery execute my configured reminders and stop them when an invoice is marked paid, so that automation runs without me keeping the app open.

• Trigger: the scheduler runs on its schedule and evaluates due steps.
• Observable result: configured reminders are dispatched and stop-on-paid is enforced.
• Failure/recovery: failed dispatches are recorded and surfaced in the activity history.
• Continuation: the scheduler continues evaluating remaining invoices and steps.

FR-23 — Timezone resolution before delivery (required_inference) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should have timezone-aware scheduling applied before automated reminder delivery, so that each send occurs at the intended local time.

• Trigger: the scheduler prepares a send for an invoice.
• Observable result: the send time is resolved in the configured timezone before dispatch.
• Failure/recovery: an unresolved timezone blocks the send rather than dispatching at an arbitrary time.
• Continuation: the resolved timezone is recorded with the send.

FR-24 — Simple, clean, non-corporate interface (explicit) As a Freelancer / Consultant, Small agency / service business operator, or Bookkeeper managing client receivables, I should work in a simple, clean, non-corporate interface, so that the product feels appropriate for a small service business rather than an enterprise billing suite.

• Trigger: any interaction with the product.
• Observable result: pages present the accepted information and controls without enterprise-style density or corporate styling.
• Failure/recovery: not applicable to a presentation constraint.
• Continuation: the constraint applies across all pages.

4. User Personas

Freelancer / Consultant

Product context. A solo service provider who invoices clients directly and has no finance department. Invoices arrive in the book one at a time or in a small batch, and the person doing the work is also the person owed the money — which is exactly why chasing feels awkward.

Primary goal. Get unpaid invoices chased without manual effort, so that following up on money never depends on remembering to send an email.

Distinct accepted responsibilities. Adds invoices manually or imports them via CSV or Google Sheets; customizes reminder tone and timing; relies on automatic pre-due and post-due reminders that stop once payment is received; reads the dashboard for overdue and recovered amounts.

Relevant inputs and decisions. Client name, email, amount, due date, status, reminder stage, and notes for each invoice; the tone and timing of the sequence; the decision to mark an invoice paid when money arrives.

Interactions with other accepted participants. The freelancer's reminders are delivered to the client's email address; the client is an outbound recipient with no product surface. The freelancer's own work is bounded by the background scheduler, which fires the configured steps and enforces stop-on-paid.

Observable success. Unpaid invoices get chased without the freelancer sending anything by hand, and the dashboard shows the overdue and recovered amounts.

Small agency / service business operator

Product context. Runs a small team's receivables across many clients. The invoice book is larger, the follow-up has to be consistent across accounts, and the operator is accountable for how the business sounds when it asks for money.

Primary goal. Keep collections follow-up consistent and polite across a large invoice book without aggressive language.

Distinct accepted responsibilities. Manages a larger invoice book; sets escalation levels and reminder sequences; monitors next reminders and recovered revenue.

Relevant inputs and decisions. The full invoice book with each invoice's status and reminder stage; the escalation levels and sequence offsets; the tone the business uses with clients.

Interactions with other accepted participants. The operator configures the sequence that the background scheduler executes and that delivers email to each client. The operator's decisions about escalation and tone shape every message a client receives.

Observable success. Every client in the book receives the same consistent, polite follow-up, and the dashboard shows next reminders and recovered revenue.

Bookkeeper managing client receivables

Product context. Maintains invoice records and payment status on behalf of client businesses. Accuracy and traceability matter more than speed, because the bookkeeper has to be able to show what was sent and when.

Primary goal. Keep accurate, auditable receivables records for each client.

Distinct accepted responsibilities. Maintains invoice records and payment status on behalf of client businesses; imports invoices; marks invoices paid so reminders stop; reviews the activity log of every reminder, reply, and status update.

Relevant inputs and decisions. Imported invoice data and its column mapping; payment status changes as payments are confirmed; the audit record of every outgoing message.

Interactions with other accepted participants. The bookkeeper's status changes directly govern whether the background scheduler sends anything further to a client. The bookkeeper's audit review depends on the activity history that the scheduler and email delivery write.

Observable success. Each client's receivables record is accurate, reminders stop the moment payment is recorded, and the activity log accounts for every reminder, reply, and status update.

5. Core User Flows

Flow 1 — Freelancer starts an account and adds a first invoice

1. The freelancer opens the Landing page and reads what Invoice Nudge does: automated polite reminders before and after the due date, stopping the moment payment lands.
2. The freelancer selects the primary action and arrives at Sign Up.
3. The freelancer submits enrollment details. On success, an account is created, a session is established, and the freelancer enters the protected workspace with an empty invoice book.
4. The Dashboard shows an empty state directing the freelancer to add an invoice manually or import one.
5. The freelancer navigates to New Invoice and enters client name, client email, amount, due date, status, reminder stage, and notes.
6. The freelancer saves. The invoice appears in Invoices and on the Dashboard, scheduled against the configured reminder sequence.
7. Failure/recovery: if validation or the save fails, the entered values are preserved, the freelancer corrects the field, and resaves.

Flow 2 — Freelancer imports an existing receivables list from CSV

1. From the protected workspace, the freelancer opens CSV Import.
2. The freelancer selects a CSV file. The page parses it and shows the column map from sheet headers to invoice fields.
3. The freelancer confirms the mapping and runs the import.
4. Imported invoices appear in Invoices with client name, email, amount, due date, status, reminder stage, and notes populated, and are scheduled against the configured reminder sequence.
5. Failure/recovery: if the file cannot be parsed or a required column is unmapped, the page identifies the problem and the affected rows; the freelancer corrects the mapping or file and re-runs the import.

Flow 3 — Freelancer connects Google Sheets and syncs invoices

1. The freelancer opens Integrations.
2. The freelancer connects a Google Sheets source and selects the sheet that supplies invoice records.
3. The freelancer maps the sheet's columns to invoice fields and runs a sync.
4. The page reports the last-sync result, and synced invoices appear in Invoices scheduled against the configured reminder sequence.
5. Failure/recovery: if authorization fails, the sheet is unavailable, or the mapping is wrong, the page reports the cause; the freelancer reconnects or corrects the mapping and re-runs the sync.

Flow 4 — Freelancer customizes tone and timing, then edits a template

1. The freelancer opens Reminder Settings and reviews the current sequence: T-3 gentle, due date polite, T+3 follow-up, T+7 firmer, T+14 final or escalation.
2. The freelancer adjusts offsets, sets the timezone used for scheduling, sets the message tone, and sets escalation levels, then saves.
3. The freelancer opens Templates and edits the message for a step, previewing it as the client will read it with its sequence step and timezone footer.
4. The freelancer saves. The saved template is used by subsequent sends for that step.
5. Failure/recovery: if the settings save fails, the edited values are preserved and the previously saved configuration remains in effect until a save succeeds. If a template save fails, the edited text is preserved and the previously saved template remains in use.

Flow 5 — Automated reminder sequence runs and stops on payment

1. The background scheduler evaluates each unpaid invoice against the configured offsets in the resolved timezone.
2. At T-3 days the gentle reminder is dispatched to the invoice's client email; at the due date the polite reminder; at T+3 the follow-up; at T+7 the firmer reminder; at T+14 the final reminder or escalation.
3. Each outgoing message is written to the audit log, and each send appears in Activity with its invoice reference, recipient, sequence step, and timestamp.
4. The freelancer opens Invoice Details for the invoice and sees the reminder timeline with past steps marked sent and the next step active.
5. The client pays. The freelancer marks the invoice paid.
6. The reminder sequence stops automatically. No further reminders are sent for that invoice, and its timeline collapses into a stopped state with the paid date.
7. The invoice contributes to the recovered amount on the Dashboard.
8. Failure/recovery: if a dispatch fails, it is recorded and surfaced in Activity rather than silently advancing the sequence. If the mark-paid change fails to persist, the prior status remains in effect and the freelancer is told the change did not save, so no reminder is suppressed on the basis of an unsaved change.

Flow 6 — Agency operator monitors next reminders and recovered revenue

1. The operator logs in at Login and lands in the protected workspace.
2. The Dashboard shows overdue amount, recovered amount, and the next reminders across the book.
3. The operator opens Invoices and scans the book by status and reminder stage; hovering a row reveals the next scheduled send in place.
4. The operator opens an invoice in Invoice Details to confirm its position in the sequence.
5. The operator adjusts escalation levels in Reminder Settings so that follow-up across many clients stays consistent and polite, and saves.
6. The operator returns to the Dashboard and confirms the next reminders reflect the updated configuration.
7. Failure/recovery: if the dashboard summaries fail to load, a clear error with retry is shown and the operator can still reach Invoices and New Invoice.

Flow 7 — Bookkeeper imports client invoices, records payment, and audits the record

1. The bookkeeper logs in at Login and opens CSV Import.
2. The bookkeeper selects a client's CSV, confirms the column mapping, and runs the import.
3. The imported invoices appear in Invoices with their fields populated and are scheduled against the configured reminder sequence.
4. A client pays. The bookkeeper opens the invoice in Invoice Details and marks it paid.
5. The reminder sequence stops automatically for that invoice, and its timeline shows the stopped state with the paid date.
6. The bookkeeper opens Activity and reviews the durable history of reminders, replies, and status updates for that client, confirming that every outgoing message has an audit record with its invoice reference, recipient, sequence step, and timestamp.
7. Failure/recovery: if the import reports row-level failures, the bookkeeper corrects the affected rows and re-runs. If the mark-paid action fails, the prior status remains in effect and the bookkeeper is told the change did not save, so reminders continue until payment is correctly recorded.

6. Visuals, Colors and Theme

Muse and headline. Adham Dannaway — two halves of one ledger: the polite letter and the machine that sends it. Invoice Nudge has exactly two natures: the email a client reads (warm, plain, human, editable prose) and the scheduler that fires it (T-3 / T+0 / T+3 / T+7 / T+14, timezone-aware, stop-on-paid, audit-logged). The design shows both at once, joined by one visible rule.

Color tokens — light mode

Dark technical insert panel (code, timeline, console surfaces only — never body prose): panel #14161A, text #E8E6E1, rule lines #8A8579, inset highlight 1px inset rgba(255,255,255,0.06), hairline #2A2D33.

Accent discipline. Ember #E4572E is reserved exclusively for money-in-motion and urgency: recovered amount, overdue state chips, the active step in the reminder timeline, and the primary CTA. Accent proportion stays under roughly 8% of any screen — a signal, not a brand wash. Paid/healthy state is calm moss #4F6B4A, never a bright positive green. No blue, indigo, or violet anywhere in the accent or CTA; the dark half is true near-black, never navy.

Typography

• Headings: Archivo (variable, including Archivo Expanded via font-variation-settings), weight 600–700, tracking -0.03em.
• Body: Archivo, weight 400, 16px, line-height 1.55.
• Machine voice: JetBrains Mono, weight 400/500, uppercase micro-labels at 11px with +0.14em tracking — used for every machine-side element: timestamps, day offsets (T-3, T+7), invoice IDs, amounts in tabular figures, log rows, cron expressions.
• The rule: if a human wrote it, it is Archivo; if the system generated it, it is JetBrains Mono. That rule is the typographic identity.
• Type scale (1.25 modular, mobile → desktop): display clamp(2.5rem, 6.2vw, 5.5rem) (40→88px), h1 32→56, h2 24→36, h3 19→24, body 16→17, mono-label 11, mono-data 13.
• Numerals always font-variant-numeric: tabular-nums; currency glyphs at 0.9em so ₹ / $ / € never outsize the figure.

Shape language. Precise and near-square: 6px radii on inputs and chips, 10px on cards, 2px on the split rule and timeline ticks. No pills, no blobs, no soft-offset shadows. Depth comes from one hard 1px hairline (#E3DED6 on paper, #2A2D33 on the dark panel) and, on the dark half only, a single 1px inset highlight at rgba(255,255,255,0.06). The one soft gesture allowed: the email preview card carries a 1px border and a 20px 40px 0 rgba(22,24,29,0.06) shadow, as if a sheet of paper laid on a desk — the only object in the system permitted to cast anything.

Layout. Split-screen is the governing idea, mirrored at every level. Landing hero: 6/6 columns at 1280px, paper half left (email preview), dark engine half right (timeline), separated by a single 1px vertical rule running the full hero height and continuing as a 1px horizontal rule through every section boundary — the seam is a navigational device, not decoration. Below 768px the split rotates to stacked and the seam becomes horizontal between blocks. Dashboard: left rail 240px with the invoice list (mono IDs, tabular amounts), right 1fr workspace; selecting an invoice slides the detail panel in from the right with the seam animating as the divider. Section rhythm is 8-pt with 96px vertical breathing at desktop, 48px at mobile. Everything flush-left ragged-right; nothing centred except the final CTA.

Imagery. No stock photography, no 3D blobs. The imagery is the product's own artefacts, art-directed: (1) a real reminder email rendered as a paper card with a visible ruled left margin, sender line, and a mono footer reading sent 09:00 IST · sequence step 3 of 5; (2) the dark engine panel showing a vertical timeline with five ticks labelled in mono T-3, DUE, T+3, T+7, T+14, the active tick in ember and a struck-through STOPPED — PAID state beside it; (3) small hand-drawn schematic diagrams (1.5px ink strokes, no fill) explaining stop-on-paid and timezone offset, drawn like a designer's margin note; (4) a CSV/Sheets import shown as a literal column map with arrows from sheet headers to schema fields. Anything that would be a screenshot is instead re-drawn as a diagram — never a browser chrome mockup.

Readable text and controls stay whole at every viewport. Headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled off an edge, rotated, or overlapped as the direction asks, as long as they cover no readable text or control. Moving and scrollable content may cross the viewport or container edge by design and is judged by whether it actually moves and whether every item becomes fully readable as it passes. With prefers-reduced-motion it stops and shows whole items, wrapping into rows or sitting in a horizontally scrollable row (overflow-x: auto).

7. Signature Design Concept

The Seam. The public entry is a full-viewport two-halves composition split by a hairline seam at exactly 50%.

Left half — warm paper ground (#FBF9F6). An oversized stacked headline in Archivo 600 at clamp(40px, 6.2vw, 88px) filling nine of twelve columns — "Your invoices, chased politely." — with the subhead directly beneath in 17px ink and the primary CTA (ember #E4572E, 6px radius, square) pinned to the baseline of the block, not centred. Beneath the copy sits a real reminder-email card, tilted 0deg, its top edge cropped by the viewport bottom so it reads as one of many. The card carries the ruled left margin, the sender line, and the mono footer sent 09:00 IST · sequence step 3 of 5.

Right half — dark #14161A panel. A vertical five-tick reminder timeline in JetBrains Mono, each tick labelled T-3 / DUE / T+3 / T+7 / T+14 with the active tick in ember, a live-looking next reminder in 06:12:44 counter, and a single struck-through row reading STOPPED — PAID 12 Mar.

The join. The seam between halves is a 1px rule that runs full height and terminates in a small mono caption at the bottom edge: "sequence stops the moment the money lands." No gradient, no blob, no centred stack, no blue.

The concept recomposes only accepted content and states: the reminder sequence steps, the stop-on-paid rule, the timezone-stamped send, and the two navigation actions to Sign Up and Login. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: expressive Hero Dimensionality: layered_2d

Landing Hero Motion Brief

• Focal subject. The two halves in dialogue: the paper reminder-email card on the left and the dark five-tick reminder timeline on the right, joined by the seam rule.
• Input → transformation → outcome thesis. On hover of either half, the opposite half dims to 92% opacity and the seam rule thickens to 2px in ember over 160ms — the visitor's attention moves between the human artefact and the machine that sends it, and the seam makes the relationship visible. On first scroll into view, the email preview types the client's first name over 400ms, once, then never again — the message becomes a real letter addressed to a real person. Timeline steps advance with a 120ms left-to-right wipe on the mono step label, so the sequence reads as a machine progressing through T-3 → DUE → T+3 → T+7 → T+14.
• Motion vocabulary. Reveal-by-hover across the split; 120ms left-to-right wipe on mono step labels; a single 400ms typing reveal of the client's first name; the seam thickening to 2px in ember. All transitions 120–200ms, cubic-bezier(0.2, 0, 0, 1). No bounce, no spring, no floating.
• Composed first frame. At rest: paper half left with the stacked headline, subhead, ember CTA on the block's baseline, and the cropped email card below; dark half right with the five-tick timeline, the active tick in ember, the live counter, and the struck-through STOPPED — PAID row; the 1px seam running full height and terminating in the mono caption.
• Reduced-motion state. Under prefers-reduced-motion every reveal becomes an instant state change, the typing effect renders the full client name immediately, the timeline shows all five ticks in their final states, and the seam sits at its resting 1px weight.

In-product motion. Hovering an invoice row swaps its status chip from the mono text state to the next scheduled date — a literal before/after within the row, no tooltip and no modal. Selecting an invoice on the Dashboard slides the detail panel in from the right with the seam animating as the divider. Under prefers-reduced-motion these become instant state changes.

9. Non-Functional Requirements

NFR-1 — Stop-on-paid enforcement (explicit). The system must never send a reminder after payment is received. The scheduler must evaluate payment status before dispatch and suppress any send for a paid invoice, recording the suppression. Rationale: this is the product's central promise and an explicit hard constraint.

NFR-2 — Default language restraint (explicit). Default reminder wording must avoid aggressive language. Rationale: explicit hard constraint; the product's politeness is a design constraint, and aggressive collections language ("final notice", "legal action", "debtor") must not appear in any template or UI copy.

NFR-3 — Full template editability (explicit). Every reminder template must be editable by the user. Rationale: explicit hard constraint.

NFR-4 — Timezone-based scheduling (explicit). Reminder scheduling must be timezone-aware, and the resolved timezone must be applied before delivery. Rationale: explicit hard constraint; a reminder must land at the intended local time.

NFR-5 — Audit logging of every outgoing message (explicit). An audit record must be kept for every outgoing message, including its invoice reference, recipient, sequence step, and send time. Rationale: explicit hard constraint; bookkeepers must be able to audit each client's receivables record.

NFR-6 — Simple, clean, non-corporate interface (explicit). The UI must be simple, clean, and non-corporate. Rationale: explicit hard constraint; the audience is small service businesses, not enterprise finance departments.

NFR-7 — Reliable background automation (required_inference). Reminder execution must not depend on the user keeping the application open; scheduling and email delivery run as background work. Rationale: indispensable to the accepted outcome of chasing unpaid invoices without manual effort.

NFR-8 — Durable per-account records (required_inference). Invoice records, reminder configuration, templates, and activity history must persist per account and remain bound to the correct user across sessions. Rationale: indispensable to resuming a private invoice book and audit history.

NFR-9 — Readable text and controls at every viewport (explicit design constraint). 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 to fit, with no other element covering any part of them. Rationale: explicit design constraint.

NFR-10 — Reduced-motion support (explicit design constraint). Under prefers-reduced-motion, reveals become instant state changes, the typing effect renders the full name immediately, and moving or scrollable content stops and shows whole items. Rationale: explicit design constraint.

10. Tech Stack

Source-specified choices are preserved exactly:

• Frontend: Next.js.
• Backend: Node.js.
• Database: PostgreSQL.
• Auth: Clerk or Supabase Auth.
• Email: Resend or SendGrid.
• Scheduler: cron jobs / background workers.
• Deployment: Vercel.

Supporting implementation choices consistent with the above:

• Background jobs: the scheduler runs as a cron-triggered background worker that evaluates invoice steps and dispatches email through the configured provider.
• Google Sheets sync: server-side integration invoked from the Integrations page.
• CSV parsing: server-side parsing with a column-mapping step before records are written.

11. Assumptions and Constraints

Assumptions

• A-1. Each signed-in user works within their own account's invoice book, reminder configuration, templates, and activity history. Multi-user team access is a deferred upgrade, so no shared-state permission model is assumed.
• A-2. The client who receives a reminder email is an outbound recipient with no product surface; the client portal is a deferred upgrade.
• A-3. The reminder sequence defaults to T-3 gentle, due date polite, T+3 follow-up, T+7 firmer, and T+14 final or escalation, and the user may customize timing, tone, and escalation levels from Reminder Settings.
• A-4. Default templates are provisioned with polite, non-aggressive wording for each sequence step so that a new account can run the sequence before the user edits anything.
• A-5. A reminder is dispatched to the client email stored on the invoice.
• A-6. Marking an invoice paid is the user action that stops the sequence; the stop is enforced by the background scheduler on the persisted payment status.

Constraints

• C-1. Never send reminders after payment is received.
• C-2. Avoid aggressive language by default.
• C-3. Allow the user to edit all templates.
• C-4. Support timezone-based scheduling.
• C-5. Keep audit logs for every outgoing message.
• C-6. Make the UI simple, clean, and non-corporate.
• C-7. The following are explicitly out of the current MVP: SMS reminders, WhatsApp reminders, late fee calculation, promise-to-pay tracking, payment links, client portal, multi-user team access, AI-generated reminder tone variations, and integrations with Stripe, Razorpay, QuickBooks, and Xero.
• C-8. No blue, indigo, or violet in the accent or CTA; the accent is ember #E4572E only, and the dark half is true near-black, never navy.
• C-9. No centred hero stack of headline, subtext, and button, and no gradient blob or mesh behind the type.
• C-10. No Inter, Roboto, Poppins, Arial, Helvetica, or system-ui for headings or body; no rounded pill buttons anywhere.
• C-11. No grid of identical hover-lift feature cards; features are shown as diagrams and split compositions instead.
• C-12. No aggressive collections language in any template or UI copy.
• C-13. No browser-chrome mockups or device frames standing in for product imagery.
• C-14. No glassmorphism, frosted panels, or blur effects on the paper half.
• C-15. Green is not a success colour; paid state is moss #4F6B4A, never a bright positive green.
• C-16. The generic indigo/blue-on-white SaaS template is forbidden for this project.

Future requirements (not part of the current MVP, not in current pages or acceptance)

The following are recorded as explicitly deferred optional upgrades: SMS reminders; WhatsApp reminders; late fee calculation; promise-to-pay tracking; payment links; client portal; multi-user team access; AI-generated reminder tone variations; and integrations with Stripe, Razorpay, QuickBooks, and Xero.

12. Glossary

• Invoice Nudge — the micro SaaS product specified by this document.
• Invoice — a receivable record holding client name, client email, amount, due date, status, reminder stage, and notes.
• Reminder stage — the invoice's current position in the reminder sequence.
• Reminder sequence — the ordered set of reminder steps relative to an invoice's due date: T-3 gentle, due date polite, T+3 follow-up, T+7 firmer, T+14 final or escalation.
• Offset — a step's distance in days from the due date, expressed as T-3, T+0 (due date), T+3, T+7, or T+14.
• Stop-on-paid — the rule that the reminder sequence halts automatically once an invoice is marked paid, and that no reminder is ever sent after payment is received.
• Reminder template — the editable message used for a given sequence step.
• Tone — the user-configured register of reminder messages, which must avoid aggressive language by default.
• Escalation level — the user-configured intensity applied as the sequence progresses toward the final step.
• Activity log — the durable history of reminders, replies, and status updates.
• Audit record — the per-message record kept for every outgoing reminder, including invoice reference, recipient, sequence step, and send time.
• Overdue amount — the total value of invoices past their due date and still unpaid, shown on the Dashboard.
• Recovered amount — the total value of invoices marked paid, shown on the Dashboard.
• Next reminders — the upcoming scheduled reminder sends shown on the Dashboard.
• Seam — the 1px rule that splits the hero at 50% and continues as a horizontal rule through section boundaries.
• Paper half / engine half — the two halves of the split composition: the human-authored message side and the machine-side scheduler side.
• Mono voice — JetBrains Mono, used for every system-generated string: timestamps, offsets, invoice IDs, amounts, log rows, and cron expressions.