InvoiceFlow

InvoiceFlow is an invoicing app for freelancers. Manage clients, create branded invoices and estimates, share public payment links, collect payments through Stripe Connect, and automate overdue reminders.

MCP server (agents)

InvoiceFlow ships a dependency-free Model Context Protocol server, so an agent in Claude Desktop, Cursor, or any MCP host can create invoices and get payable Stripe links without reading a REST document.

{
  "mcpServers": {
    "invoiceflow": {
      "command": "node",
      "args": ["/abs/path/invoiceflow-mcp.mjs"],
      "env": { "INVOICEFLOW_API_KEY": "ifk_..." }
    }
  }
}

Download the server from https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-mcp.mjs.

Tools: whoami, create_client, list_clients, create_invoice, list_invoices, get_invoice, share_invoice.

The omissions are the design. No tool sends email, deletes, refunds, or pays. Creating an invoice is additive and a human can undo it; an agent that emails a customer on every retry cannot take that back. Amounts are integer cents named unitPrice, and a non-integer is refused with an explanation rather than rounded, because 25.5 silently meaning 25 cents is the defect most likely to reach a real customer.

Verify it yourself, no account required:

curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-mcp.mjs
curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-client.mjs
curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/test-mcp.mjs
node test-mcp.mjs     # 14 passed, 0 failed — no key, no network

---

Stack

• Node.js 22 and pnpm 10.34.9 (packageManager in package.json)
• Next.js 15 App Router, React 18, TypeScript, Tailwind CSS and Framer Motion
• NextAuth v5 with Google OAuth and JWT sessions
• Prisma 5 and PostgreSQL 16; Docker Compose locally, Neon for deployment
• Stripe Connect Express and Checkout; Resend and React Email
• Vitest unit and PostgreSQL integration tests; ESLint and GitHub Actions

Implemented workflows

Area	Behavior
Clients and invoices	Owner-scoped management, line items, percentage tax, draft editing and controlled status changes
Invoice delivery	Save & Send calls the email endpoint; accepted email uses a stable public link, failed delivery keeps one saved draft, explicit resends are available
Public invoices	Branded view, readable multi-page PDF export with saved notes and correct tax breakdown, unguessable share tokens and noindex metadata
Online payments	Tax-inclusive grand total, reuse of open Checkout sessions, signed webhook reconciliation
Reminders	Escalating email reminders for sent and overdue invoices
Recurring invoices	Scheduled draft generation and schedule advancement in one database transaction
Estimates	Create and manage estimates; convert an estimate to an invoice once
Reports and exports	Revenue, outstanding balances, aging, client reports and CSV export
Business profile	Name, address, logo, accent color and invoice numbering prefix

Every account starts with a 14-day free trial; InvoiceFlow Pro then costs US$9/month through Stripe Checkout, with card changes and cancellation in the Stripe billing portal. After the trial, creating and sending invoices requires an active subscription; existing records, PDFs, exports and clients' payments stay available. Invoice payments go to each user's own Stripe account and are separate from their InvoiceFlow subscription. Decisions are recorded in the launch spec.

Interface and design guidance

The public site, Google sign-in and workspace use a warm-white, dark-ink and evergreen visual system, with an interactive example invoice, compact tables and keyboard-friendly mobile navigation. Reports retain separate totals for each currency. Client creation is available inside invoice and estimate drafts.

Read PRODUCT.md and DESIGN.md before changing the interface. The requested Emil Kowalski, Impeccable, Taste and frontend-design skills are installed locally under .agents/skills, with upstream revisions and licenses. The design review records rendered checks and deliberate tradeoffs.

Local development

Install Node.js 22 and the pinned pnpm version first. Keep existing local configuration rather than replacing it.

pnpm install --frozen-lockfile
test -e .env || cp .env.example .env
# Configure .env before continuing.
docker compose up -d --wait
pnpm run db:generate
pnpm run db:deploy
pnpm run dev

Use the local PostgreSQL URL from .env.example for both DATABASE_URL and DATABASE_URL_UNPOOLED. Generate an AUTH_SECRET, add Google OAuth credentials, and use http://localhost:3000 for NEXTAUTH_URL and NEXT_PUBLIC_APP_URL. Register http://localhost:3000/api/auth/callback/google in the Google OAuth client.

Leave optional Stripe and Resend keys empty until you have valid credentials; the example strings are placeholders. Unconfigured integrations return an unavailable response. Google sign-in and the full send/pay workflow require their actual service configuration.

pnpm run db:deploy applies committed migrations to a new development database. If an existing database was created using prisma db push, follow the baseline procedure before applying migrations. Never use db push or migrate reset to deploy production schema changes.

The Compose database uses a persistent named volume. docker compose down stops it without deleting that volume.

Optional demo data:

# Only against a disposable development database.
pnpm run db:seed

The seed replaces the account selected by SEED_DEMO_EMAIL (default [email protected]) and its related data. Do not target a real customer account or production database.

PDF exports

PDF downloads use a measured A4 layout with separate sender/recipient blocks, issue/due dates, currency, status, itemized charges, tax and total. Long records paginate with repeated table headings. Saved invoice Notes are included under “Notes & payment instructions”; payment details and a billing period can be entered there. The PDF reflects the saved invoice amounts and does not change payment status or data.

View the synthetic PDF example and layout review. Generate short, normal and long review fixtures without database/provider access:

pnpm exec tsx scripts/preview-invoice-pdf.ts

Configuration

Variable	Use
DATABASE_URL	Prisma runtime PostgreSQL connection; use Neon's pooled URL in deployment
DATABASE_URL_UNPOOLED	Direct database connection for Prisma migrations
AUTH_SECRET	Stable, private NextAuth signing/encryption secret
AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET	Google web OAuth client credentials
NEXTAUTH_URL	Canonical auth origin; HTTPS in production
AUTH_TRUST_HOST	Set to true only behind the trusted deployment proxy, such as Vercel
NEXT_PUBLIC_APP_URL	Canonical public HTTPS origin for invoice, payment and email URLs
STRIPE_SECRET_KEY	Stripe platform API key for Connect and Checkout
STRIPE_WEBHOOK_SECRET	Signing secret for this deployment's connected-account webhook endpoint
STRIPE_CONNECT_COUNTRY	Supported Connect country for newly created accounts; defaults to US
RESEND_API_KEY, RESEND_FROM_EMAIL	Email API key and a sender on a verified Resend domain
FREELANCER_NOTIFY_EMAIL	Fallback only when the invoice owner has no email address
CRON_SECRET	Bearer secret for scheduled invoice generation and reminders
SEED_DEMO_EMAIL	Disposable account targeted by the destructive demo seed

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY is reserved in the example configuration; the current hosted Checkout redirect does not use a browser Stripe SDK. The INNGEST_* variables are also unused.

Keep secrets in ignored local environment files or the hosting provider's secure settings. Preview and production deployments should use separate databases and service keys.

Validation

pnpm test
pnpm run lint
NEXT_PUBLIC_APP_URL=https://invoiceflow.example.test pnpm run build
pnpm run typecheck
# After building, against the disposable local test DB:
pnpm run test:browser
pnpm audit --prod --audit-level high

For these local browser checks, the build uses the HTTPS test origin above; Vercel releases use the real configured production origin. Next.js embeds NEXT_PUBLIC_APP_URL during the build.

The build generates Prisma Client, compiles all routes, and produces the production application. Production Vercel builds first verify and migrate the database with a guarded release step; local and preview builds require explicit database preparation. Google Fonts access is needed for the configured next/font loader. Prisma downloads must retain TLS and checksum verification.

Integration tests use a separate disposable local database named invoiceflow_test. Create it once:

docker compose exec -T db createdb -U postgres invoiceflow_test

Then run:

export DATABASE_URL='postgresql://postgres:postgres@localhost:5432/invoiceflow_test?schema=public'
export DATABASE_URL_UNPOOLED="$DATABASE_URL"
pnpm run db:deploy
pnpm run test:integration

Run these exports in a separate shell from the development server. The suite rejects remote databases and other database names. It uses real PostgreSQL transactions and signed Stripe fixtures, with external Stripe/Resend requests mocked. It covers invoice totals, public links, checkout reuse, webhook verification and retries, concurrent numbering/conversion, and recurring transaction rollback. It does not establish that live OAuth, payment or email credentials work.

GitHub Actions runs frozen installation, Prisma generation, migrations, lint, unit/integration tests, the production build, Chromium browser workflows, typechecking and a production dependency audit using PostgreSQL 16 and Node.js 22.

Deployment

Use the Vercel and Neon release guide for migration handling, service configuration, scheduled jobs and the required test-mode release smoke test. Passing local checks is separate from validating a deployed application.

Scheduled jobs

Both jobs use GET and require Authorization: Bearer <CRON_SECRET>:

• /api/cron/generate-recurring creates due draft invoices and advances their schedules.
• /api/cron/chase-invoices sends due reminders.

vercel.json schedules generation at 00:00 UTC and reminders at 09:00 UTC each day. Vercel sends the bearer header when CRON_SECRET is configured. Check the plan's scheduling and function-duration limits before enabling a larger workload.

Current product boundaries

• Online Checkout supports currencies with two decimal places and positive totals within its validated amount limit. It charges one tax-inclusive invoice total; the public invoice supplies the breakdown.
• Dashboard and reports show monetary totals for the selected currency. They do not convert currencies or provide a consolidated foreign-exchange total. Recent invoices display their own currency.
• Public payment IP throttling is in memory and therefore best effort across Vercel instances. A distributed rate limiter is needed for a larger deployment.
• Payment confirmation email currently goes to the invoice owner, not a separate customer receipt workflow.
• Recurring jobs create drafts; they do not automatically send them or charge stored payment methods.
• Refunds, partial invoice payments and per-invoice accounting require separate product work. InvoiceFlow Pro has one monthly plan; there are no annual plans, coupons or team seats.

Architecture

                           ┌─────────────────────────────┐
                           │      Client / Browser       │
                           └──────────────┬──────────────┘
                                          │
                                          ▼
                         ┌─────────────────────────────────┐
                         │   Next.js Middleware (Auth)     │
                         └──────────────┬──────────────────┘
                                        │
        ┌───────────────────────────────┼───────────────────────────────┐
        ▼                               ▼                               ▼
 ┌──────────────┐             ┌──────────────────┐            ┌──────────────────┐
 │ Landing Page │             │ Dashboard (App)  │            │  Public Invoice  │
 │     `/`      │             │  `/(dashboard)`  │            │   `/i/[token]`   │
 └──────────────┘             └─────────┬────────┘            └────────┬─────────┘
                                        │                              │
                                        ▼                              ▼
                         ┌─────────────────────────────────────────────────┐
                         │               API Routes & Crons                │
                         │   • /api/invoices        • /api/estimates       │
                         │   • /api/clients         • /api/cron/*          │
                         │   • /api/i/[token]/pay   • /api/webhooks/stripe │
                         └──────────────────────┬──────────────────────────┘
                                                │
         ┌──────────────────────────────────────┼──────────────────────────────────────┐
         ▼                                      ▼                                      ▼
┌──────────────────┐                  ┌──────────────────┐                   ┌──────────────────┐
│  Neon Postgres   │                  │  Stripe Connect  │                   │      Resend      │
│  (Prisma Engine) │                  │ (Checkout & Web) │                   │  (React Emails)  │
└──────────────────┘                  └──────────────────┘                   └──────────────────┘

---

Structure

prisma/             Schema, migrations and disposable demo seed
src/app/            Marketing, authenticated app, public invoices and API routes
src/lib/            Billing, auth, money, reporting, validation and integrations
src/emails/         React Email templates
src/components/     UI, reports and marketing components
integration/        PostgreSQL-backed billing regression tests
.github/workflows/  CI

Browser workflow tests

Run pnpm run test:browser after pnpm run build, with DATABASE_URL and DATABASE_URL_UNPOOLED pointing to the disposable local invoiceflow_test database. Install Chromium using pnpm exec playwright install chromium when a system Chromium is unavailable. Browser tests start a production server on port 3100, use isolated test accounts and a locally signed session, and exercise actual pages, API requests and database writes. The design checks cover 13 routes at desktop (1440px), tablet (768px) and phone (390px) widths, including public invoices, invoice/estimate details, keyboard interactions, reduced motion and mobile sign-out. PDF browser tests also exercise the Download PDF button, parse the exported values and notes, and reject cross-account or unauthenticated downloads. They do not complete Google OAuth or send real emails/payments. Provider HTTP responses come from guarded local fixtures loaded only into the test server. These fixtures exercise the actual Resend/Stripe SDK requests while blocking unmatched external requests. Browser checks cover Save & Send, provider rejection and retry, explicit resend, existing issued invoices, Stripe readiness reconciliation and the Checkout redirect. See delivery and payment checks for production setup and the distinction between email acceptance and inbox delivery.