invoice-builder copilot-instructions.md

Copilot instructions for Invoice Builder

Overview

This repository is an Electron app with a separate backend webserver used for the web/docker mode. Key runtime pieces are:

• Electron main process: built by vite via vite.electron.config.ts -> outputs dist-be/backend/main/main.cjs
• Preload script: src/preload/preload.ts -> built with vite.preload.config.ts -> outputs dist-be/preload/preload.cjs
• Renderer (React + Vite): src/renderer (dev: vite, build: vite build)
• Optional backend webserver: src/backend/webserver/main.ts (dev: npm run dev:webserver, build: npm run build:webserver)
• Migrations: source files in src/backend/shared/migrations, built into dist-be/backend/migrations using vite.migrations.config.ts.

BMAD-inspired workflow for agentic development

This repository uses a lightweight BMAD-style workflow for coding tasks. See AGENTS.md for the complete workflow guide, including when to use this workflow, default verification checks, and team expectations.

For new work with the agent-based approach:

• Use the po agent with bmad-po.prompt.md for acceptance criteria and scope clarification.
• Use the dev agent with bmad-dev.prompt.md for implementation.
• Use the qa agent with bmad-qa.prompt.md for review and verification.
• Use the delivery agent with bmad-delivery.prompt.md for slicing and sequencing release work.
• Use the scrum agent with bmad-scrum.prompt.md for sprint planning and execution cadence.

Repository-specific expectations:

• UI work usually touches src/renderer.
• IPC or preload changes require matching updates in src/preload/preload.ts and the Electron main process under src/backend/main.
• Database or persistence changes should be reviewed for migrations under src/backend/shared/migrations.
• Webserver changes should be validated through the appropriate build or dev workflow.

Primary developer commands

• Full local dev (electron + renderer + preload + migrations):
  • npm run dev
• Frontend-only dev: npm run dev:react (uses Vite)
• Backend webserver dev: npm run dev:webserver (runs src/backend/webserver/main.ts via tsx)
• Build production bundles: npm run build (runs build:react, build:preload, build:migrations, build:electron)
• Package for Windows: npm run package (calls electron-builder)
• Tests: npm test (runs vitest), coverage: npm run test:coverage

Important patterns and conventions

• Multi-config Vite builds: see vite.electron.config.ts, vite.preload.config.ts, and vite.migrations.config.ts. When adding runtime files for main/preload/migrations, update those configs.
• IPC surface is declared in src/preload/preload.ts as window.electronAPI. When adding or renaming IPC channels:
  • Add/remove the ipcMain handlers in the Electron main process (src/backend/main)
  • Mirror the channel name and typings in src/preload/preload.ts and update related renderer types under src/renderer/shared/types
  • Keep the exposed function names stable (renderer code expects methods like electronAPI.getAllInvoices, electronAPI.addInvoice).
• Web vs Electron mode:
  • Renderer detects runtime via isWebMode() (see src/renderer/shared/api/restApi) and either calls the web API or talks to window.electronAPI.
  • Mocking: MSW is enabled via VITE_ENABLE_MOCKS (set in .env.*), and the renderer starts the worker in src/renderer/main.tsx.
• Database & migrations:
  • Migrations live in src/backend/shared/migrations and are built into dist-be/backend/migrations. Use npm run build:migrations for CI packaging.
  • The app uses SQLite (sqlite3). Be careful when changing schema—migrations need to run in a controlled order.