How to Build an Invoice App

<context>
App: Invoice App
Difficulty: Intermediate
Estimated build time: 3–7 days

Data model:
  User: id, email, business_name, address, tax_number, logo_url
  Client: id, user_id, name, email, address, currency
  Invoice: id, user_id, client_id, number, status (draft/sent/viewed/paid/overdue), due_date, subtotal, tax_rate, total, notes, stripe_payment_link, sent_at, paid_at
  LineItem: id, invoice_id, description, quantity, unit_price, total

Recommended build order:
  1. Invoice builder UI — Build the invoice form: your business details, client selector, line items table (description, qty, unit price, total auto-calculated), tax rate, and notes. Show a live preview alongside.
  2. PDF generation — Use @react-pdf/renderer to define the invoice layout as React components. Call pdf().toBlob() to generate a PDF on demand. Show a download button and a preview iframe.
  3. Client management — Create a clients table. Add a client selector to the invoice form. On selecting a client, auto-fill their address and currency. Add a simple client list page.
  4. Invoice numbering and status — Auto-increment invoice numbers (INV-001, INV-002). Add a status field: draft → sent → viewed → paid → overdue. Update status when: you send it, the client opens it, Stripe confirms payment.
  5. Send by email with pay-by-link — Create a Stripe Payment Link for the invoice total. Send an email via Resend with the invoice PDF attached and the pay link. Track when the link is opened using a redirect through your app.
  6. Automatic payment reminders — A daily cron job checks for invoices where due_date < today AND status != paid. For each overdue invoice, send a polite reminder email with the pay link. Cap at 3 reminders.
  7. Recurring invoices — Add a recurring boolean and interval (monthly/weekly) to invoices. A cron job duplicates the invoice on the correct date, resets status to draft, increments the number, and optionally auto-sends.

Known pitfalls to avoid:
  - Generating PDF on the server without a headless browser — @react-pdf/renderer works in Node.js without Puppeteer. Don't reach for Puppeteer (which needs a full Chrome install) until you outgrow react-pdf.
  - Marking invoices paid based on email reply — only trust Stripe webhooks (payment_intent.succeeded) to mark an invoice paid. Never mark it paid based on a customer email or manual input without verification.
  - Forgetting to handle partial payments — if a client pays $500 of a $1000 invoice via bank transfer, your status machine needs a partial state. Add amount_paid alongside the status field.

Tech stack (intermediate): Next.js + Supabase + Stripe + react-pdf + Resend — full pay-by-link flow
</context>

<role>
You are a Senior Full-Stack Engineer and product architect who has shipped production Invoice Apps before. You know exactly where developers get stuck and how to structure the project to avoid rewrites.
</role>

<task id="step-1-clarify">
Before writing any code or spec, ask me 3–5 clarifying questions that will meaningfully change the architecture. Focus on: scale expectations, auth requirements, platform (web / mobile / both), must-have vs nice-to-have features for the MVP, and any hard constraints (budget, deadline, existing infrastructure).

<example>
BAD: "What tech stack do you want to use?" — too broad, doesn't change architecture decisions.
GOOD: "Do you need real-time sync across devices, or is single-device with periodic refresh acceptable? This decides whether we use WebSockets or simple REST polling and significantly affects infrastructure complexity."
</example>
</task>

<task id="step-2-architect">
After I answer your questions, generate a complete project specification including:

1. Final tech stack with version numbers
2. Full file and folder structure
3. Complete database schema — every table, column, type, index, and foreign key
4. All API routes with request/response shapes and auth requirements
5. Component tree with TypeScript props interfaces
6. Auth and authorisation flow (who can do what)
7. Step-by-step implementation plan in the exact build order from <context> above
8. All environment variables with descriptions

<self_check>
Before presenting the spec, verify:
□ Every answer I gave in step 1 is reflected in the spec
□ The database schema matches the data model in <context>
□ The implementation plan follows the build order from <context>
□ No circular dependencies in the component tree
□ Auth is wired up before any protected routes are built
□ All known pitfalls from <context> are addressed in the spec
</self_check>
</task>

<task id="step-2.5-agents-md">
Generate an AGENTS.md file at the project root. This file is read automatically by Claude Code, Cursor, Windsurf, Sourcegraph Cody, and all major AI coding tools at the start of every session.

Include:
- Project overview (2–3 sentences)
- Tech stack with version numbers
- Folder structure with one-line descriptions
- Key architectural decisions and why they were made
- Coding conventions: naming (camelCase components, kebab-case files), max 200 lines per file, one concern per file
- Available commands: dev, build, test, lint, db:migrate, db:seed

Note in the file: "Cursor users can symlink .cursorrules → AGENTS.md. Claude Code users can symlink CLAUDE.md → AGENTS.md."
</task>

<task id="step-3-implement">
Implement the full project following the spec from step 2, in the exact order defined. For each step:
- Write the complete code (no placeholders or TODOs)
- Confirm the step is working before moving to the next
- Note any deviations from the spec with an explanation

<constraints>
- Max 200 lines per file. WHY: every file must fit in one AI context window for easy review and editing.
- One concern per file. WHY: mixing auth logic into API routes makes it impossible to reuse — extract to lib/auth.ts.
- TypeScript strict mode, no `any` types. WHY: catches data shape mismatches at compile time, not in production at 2am.
- All database queries in server components or API routes only. WHY: keeps credentials server-side, prevents accidental client-side exposure.
- All environment variables documented in .env.example. WHY: the next developer (or your future self) should be able to set up the project in under 5 minutes.
- Comment every non-obvious decision. WHY: AI tools read your comments to understand intent — without them, the next edit will break the pattern you established.
</constraints>
</task>