Invoice Studio

Invoice Studio is a modern invoicing web app for freelancers. It supports multi-user authentication, client management, invoice creation with line items, analytics, and server-side PDF export.

Features

• Email/password authentication with password reset via Resend
• Profile defaults for company info, terms, and notes
• Client management embedded in invoice creation
• Auto-sequential invoice numbers per client
• Dashboard metrics (by client, month, and year)
• Server-generated PDF export
• Light/dark mode with modern UI

Tech Stack

• Next.js 15 (App Router, Server Actions)
• PostgreSQL + Prisma
• Auth.js (NextAuth) Credentials provider
• shadcn-style UI components + Tailwind CSS
• Vitest + Testing Library (unit tests)
• Playwright (e2e tests)

Prerequisites

• Node.js 20+
• pnpm 10+
• PostgreSQL (local) or Docker

Environment Variables

Copy env.example to .env and update values:

cp env.example .env

Key variables:

• DATABASE_URL
• AUTH_SECRET (generate via openssl rand -base64 32)
• AUTH_URL and NEXT_PUBLIC_APP_URL
• RESEND_API_KEY and RESEND_FROM_EMAIL

Local Development

Install dependencies:

pnpm install

Generate Prisma client and run migrations:

pnpm --filter @invoice/db db:generate
pnpm --filter @invoice/db db:migrate

Run the app:

pnpm --filter web dev

Open http://localhost:3000.

Docker

Start the app and database:

docker compose up --build

The app runs at http://localhost:3000.

Testing

Unit tests (80% coverage target):

pnpm --filter web test

E2E tests:

pnpm --filter web test:e2e

Playwright requires browser binaries:

pnpm --filter web exec playwright install

Production Notes

• Use docker compose up --build or build the Docker image via docker build ..
• Ensure AUTH_URL and NEXT_PUBLIC_APP_URL match your deployment domain.

SonarCloud (GitHub-native)

This repo includes .github/workflows/ci-sonar.yml for CI plus SonarCloud analysis on pull requests and pushes to master.

Repository settings required:

• Secret: SONAR_TOKEN
• Variable: SONAR_ORGANIZATION
• Variable: SONAR_PROJECT_KEY

Notes:

• Sonar analysis uses sonar-project.properties.
• Coverage is imported from apps/web/coverage/lcov.info generated by Vitest.
• The workflow waits for the quality gate and fails the check when it does not pass.

CodeRabbit (AI PR Review)

This repo includes .coderabbit.yaml with monorepo-aware defaults to keep reviews focused on source/workflow changes and skip generated/build artifacts.

Setup in GitHub:

• Install the CodeRabbit GitHub App for this repository from the marketplace: https://github.com/marketplace/coderabbitai
• Open a new pull request (or update an existing one) so CodeRabbit posts its first review.
• (Optional) Make CodeRabbit a required branch protection check after it appears in your PR checks.

Current defaults in .coderabbit.yaml:

• Auto-review enabled on non-draft PRs
• Assertive review profile
• High-level summary + review status enabled
• Path filtering for monorepo folders (apps/**, packages/**, .github/workflows/**) and common root config/docs

Linear Sync (GitHub -> Linear)

This repo includes .github/workflows/linear-sync.yml to sync roadmap-labeled GitHub issues into Linear and keep status aligned.

Repository settings required:

• Secret: LINEAR_API_KEY
• Variable: LINEAR_TEAM_ID
• Variable: LINEAR_PROJECT_ID

Sync behavior:

• Creates a Linear issue when a roadmap-labeled GitHub issue is opened/reopened/labeled.
• Updates Linear title/description when the GitHub issue is edited.
• Syncs milestone assignment when GitHub issue milestones are added/changed/removed.
• Moves Linear issue to completed when the GitHub issue is closed.
• Moves Linear issue back to unstarted when the GitHub issue is reopened.
• Uses the same roadmap label rules as project auto-add (area/*, type/*, effort/*, or roadmap).

GitHub Project Automation

This repo includes .github/workflows/project-auto-add.yml to automatically add newly opened/reopened issues and PRs to the roadmap project board.

Filter rules:

• The workflow only auto-adds items that are classified as roadmap using labels:
  • Prefixes: area/, type/, effort/
  • Exact label: roadmap
• It listens to opened, reopened, and labeled events for issues and PRs, so items are added when labels are applied after creation.

Required repository secret:

• PROJECT_AUTOMATION_TOKEN: GitHub token with permission to write to Projects (Project v2). For a classic token, include project and repo scopes.

Current target project:

• Owner: crisesarmiento
• Project number: 2 (Invoice Scope Roadmap)

PR Metadata Policy (GitHub + Linear Alignment)

This repo includes:

• .github/pull_request_template.md to standardize PR content.
• .github/workflows/pr-metadata-guard.yml to enforce required metadata on every pull request.

Required PR metadata:

• Milestone assigned
• At least one assignee
• Labels covering all three categories: type/*, area/*, effort/*
• Linked GitHub issues (including at least one closing keyword like Closes #6)
• Linked Linear issue references (for example CE-189 or a Linear URL)
• PR added to GitHub project Invoice Scope Roadmap