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.mjscurl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-client.mjscurl -sO https://invoiceflow-ten-azure.vercel.app/sdk/test-mcp.mjsnode 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

The app offers early access. Subscription purchases and plan enforcement are not implemented. Invoice payments are separate from billing users for access to InvoiceFlow.

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-lockfiletest -e .env || cp .env.example .env# Configure .env before continuing.docker compose up -d --waitpnpm run db:generatepnpm run db:deploypnpm 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

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 testpnpm run lintNEXT_PUBLIC_APP_URL=https://invoiceflow.example.test pnpm run buildpnpm run typecheck# After building, against the disposable local test DB:pnpm run test:browserpnpm 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:deploypnpm 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.
• Invoice/subscription accounting, refunds, partial payments and SaaS plan billing require separate product work.

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 seedsrc/app/            Marketing, authenticated app, public invoices and API routessrc/lib/            Billing, auth, money, reporting, validation and integrationssrc/emails/         React Email templatessrc/components/     UI, reports and marketing componentsintegration/        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.