InvoiceFlow

InvoiceFlow

Professional invoices, Stripe payment links, reminders, and currency-safe reporting. 14 days free, then US$9/month.

-000000?style=flat-square&logo=next.js&logoColor=white)

Features • Architecture • Local Development • Deployment

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

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 demo@invoiceflow.dev) 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 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 re