Usability overhaul: payment workflow, person-centric contacts, command palette, and systemic fixes

.env.example

@@ -13,3 +13,11 @@ SMTP_PORT=587
 SMTP_USER=
 SMTP_PASS=
 SMTP_FROM=
+
+# Automatic SQLite backups (optional - sensible defaults are used if unset)
+# Directory where backup files are written (default: ./data/backups)
+BACKUP_DIR=./data/backups
+# How often to run a backup, in hours. Set to 0 to disable backups entirely (default: 24)
+BACKUP_INTERVAL_HOURS=24
+# How many of the newest backups to keep; older ones are deleted (default: 7)
+BACKUP_RETENTION=7

CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md — guidance for AI coding agents
+
+Client Flow is a business-management app: a React/Vite frontend with a local
+Express/SQLite (better-sqlite3) backend. The frontend talks to the backend
+through a **Supabase-compatible client shim** (`src/integrations/api/client.ts`),
+so app code reads like Supabase but there is no Supabase at runtime.
+
+## Commands
+
+```bash
+npm run dev          # frontend (:8080) + backend (:3001) together
+npm run dev:client   # Vite only
+npm run dev:server   # API server only (tsx watch)
+npm run build        # production build
+npm run lint         # ESLint (note: repo has pre-existing lint debt)
+npm run typecheck    # tsc --noEmit for the server project
+npm run test         # Vitest (watch)
+npm run test:run     # Vitest (once) — server integration tests
+npm run db:reset     # delete data/app.db and restart the server
+```
+
+## Architecture
+
+```
+Frontend (React/Vite :8080)  <-->  Backend (Express/SQLite :3001)
+  src/integrations/api/client.ts     server/
+  (Supabase-compatible shim)         ├── index.ts            app wiring, CORS, rate limiting
+                                     ├── db/{schema.sql, seed.sql, database.ts, columns.ts}
+                                     ├── routes/{auth,crud,storage,functions,
+                                     │           external-api,bill-import,mail}.ts
+                                     ├── middleware/auth.ts   JWT + permissions
+                                     └── utils/{numbering,activityLogger,email}.ts
+mcp-server/   local MCP server exposing the external API to AI agents
+openapi.yaml  OpenAPI 3.1 contract for /api/external
+```
+
+The `crud.ts` router implements the Supabase-style query surface (select with
+relations, filters like `col.eq.value`, order, limit) over SQLite. Table and
+**column names are validated** against real columns (`db/columns.ts`) before
+being interpolated — never interpolate a caller-supplied identifier without
+validating it.
+
+## Security model (do not regress)
+
+- Auth is JWT (`middleware/auth.ts`); `authMiddleware` re-checks the user is
+  active on every request. Passwords are bcrypt.
+- Onboarding is **invite-based**: `POST /auth/users` (requires `team:write`)
+  creates a user with an invite token; `POST /auth/accept-invite` sets the
+  password. Login never auto-creates passwords.
+- The external API (`/api/external`, `routes/external-api.ts`) authenticates
+  with hashed API keys and is gated by the key's **scopes** AND the owning
+  user's role. Keys are created at `/api-keys`.
+- In production the server refuses to boot with a placeholder `JWT_SECRET`.
+
+## Numbering
+
+Invoice/job numbers come from atomic counters in `company_settings`, allocated
+via `server/utils/numbering.ts` (`allocateInvoiceNumber` / `allocateJobNumber`)
+inside a transaction. The frontend reserves a number at save time via
+`POST /api/functions/allocate-invoice-number`. Do NOT generate numbers with
+`COUNT(*)` or a client-side read-modify-write — both reuse/collide.
+
+## Project structure (frontend)
+
+```
+src/
+├── components/ui/     shadcn/ui — DO NOT modify (add via `npx shadcn@latest add`)
+├── components/        feature components (PascalCase)
+├── pages/             route pages (PascalCase), lazy-loaded in App.tsx
+├── hooks/             custom hooks (useXxx.ts)
+├── contexts/          React contexts (Auth, Permission, Branding)
+├── integrations/api/  the API client shim
+└── lib/utils.ts       cn(), uuid
+```
+
+## Conventions
+
+- Import order: React → external libs → `@/components/ui/*` → `@/components/*`
+  → `@/hooks/*` → `@/contexts/*` → `@/integrations/*` → `@/lib/*` → types.
+  Always use the `@/` alias.
+- Naming: Pages/Components PascalCase; ui components lowercase-hyphen; hooks
+  `useX`; handlers `handleX`; types PascalCase.
+- Styling: Tailwind only; use `cn()` for conditional classes. No inline styles.
+- User-facing errors go through `useToast` →
+  `toast({ title, description, variant: 'destructive' })`.
+- TypeScript strictness is relaxed on the frontend; the **server project
+  typechecks cleanly** (`npm run typecheck`) — keep it that way.
+
+## Testing
+
+Server integration tests live in `server/__tests__/` (Vitest + supertest over a
+temp SQLite). They assert the security and numbering invariants — run
+`npm run test:run` before committing server changes, and add a test when you fix
+a backend bug. CI (`.github/workflows/ci.yml`) gates on typecheck + tests +
+build + docker build.
+
+## Gotchas
+
+- better-sqlite3 is **synchronous** and built with `SQLITE_DQS=0`: use
+  single-quoted SQL string literals (`datetime('now')`, not `"now"`), or the
+  statement throws.
+- The DB is a singleton keyed off `DATABASE_PATH`; tests set env vars before
+  dynamically importing the app.
+- `server/uploads/` and `data/` are gitignored; storage paths are contained to
+  their bucket dir (no traversal).
+
+## Environment
+
+```bash
+VITE_API_URL=http://localhost:3001/api
+API_PORT=3001
+DATABASE_PATH=./data/app.db
+JWT_SECRET=change-me            # required; must be non-placeholder in production
+CORS_ORIGIN=http://localhost:8080
+# SMTP_* optional, for invoice/invite email
+```

README.md

@@ -109,6 +109,17 @@ Programmatic access for integrations and AI tools:
 - **Vendor Spend** - Spending by vendor
 - **GST Summary** - Tax summary
 
+### Backups
+
+The server automatically backs up the SQLite database on startup and on a recurring interval, using better-sqlite3's online backup API (safe to run while the app is live):
+
+- Backups are written to `BACKUP_DIR` (default `data/backups`, already gitignored) as `app-YYYYMMDD-HHmmss.db`
+- Runs every `BACKUP_INTERVAL_HOURS` (default `24`); set to `0` to disable
+- Only the newest `BACKUP_RETENTION` backups are kept (default `7`); older ones are deleted automatically
+- A backup failure is logged but never crashes the server
+
+Configure these in `.env.local` if you want different values - see `.env.example`.
+
 ## Notes
 
 - The local database file lives at `data/app.db` and is gitignored.

api-examples.md

@@ -431,3 +431,12 @@ curl -s -X POST "$BASE_URL/clients" \
   -H "Content-Type: application/json" \
   -d '{"name": "Test Client", "is_active": 1}' | jq .
 ```
+
+---
+
+## API reference (OpenAPI)
+
+The full machine-readable contract for this API — every resource, path, request/response
+schema, auth scheme, and error shape — is defined in [`openapi.yaml`](./openapi.yaml) at the
+repo root (OpenAPI 3.1). Load it into any OpenAPI-aware tool (Redoc, Swagger UI, Postman,
+an LLM/codegen client, etc.) to browse or generate clients from it.

mcp-server/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.env

mcp-server/README.md

@@ -0,0 +1,93 @@
+# clientflow-mcp
+
+A local [MCP](https://modelcontextprotocol.io) server that lets an AI agent (Claude Desktop,
+etc.) drive the **Client Flow** app through its external REST API (`/api/external`) using a
+scoped API key. It exposes generic CRUD tools over every resource the external API supports.
+
+> **Security:** this server adds no privileges. Every call is gated server-side by the API
+> key's **scopes** and the owning user's **role**. Create narrowly-scoped keys at `/api-keys`
+> and treat the key like a password.
+
+## Requirements
+
+- Node.js 18+
+- A running Client Flow server
+- An API key created in the app at **/api-keys**
+
+## Build
+
+```sh
+cd mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+Two environment variables:
+
+| Variable             | Example                       | Notes                                              |
+| -------------------- | ----------------------------- | -------------------------------------------------- |
+| `CLIENTFLOW_API_URL` | `http://localhost:3001/api`   | Base URL of the app (with or without trailing `/api`). |
+| `CLIENTFLOW_API_KEY` | `sk_live_...`                 | An API key from `/api-keys`.                       |
+
+The server refuses to start if either is missing (and never prints the key).
+
+## Add to Claude Desktop
+
+Add this to your `claude_desktop_config.json` (adjust the path to `dist/index.js`):
+
+```json
+{
+  "mcpServers": {
+    "clientflow": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
+      "env": {
+        "CLIENTFLOW_API_URL": "http://localhost:3001/api",
+        "CLIENTFLOW_API_KEY": "sk_live_replace_me"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool             | Purpose                                             | Hints                          |
+| ---------------- | --------------------------------------------------- | ------------------------------ |
+| `list_resources` | List available resources and their permission groups | read-only                      |
+| `list_records`   | List records of a resource (max 100, no server filtering; use `limit`) | read-only |
+| `get_record`     | Fetch one record by id                              | read-only                      |
+| `create_record`  | Create a record from column/value pairs             | write                          |
+| `update_record`  | Update fields on a record by id                     | write, idempotent              |
+| `delete_record`  | Delete a record by id                               | write, **destructive**         |
+
+Resources (gated by the permission group in parentheses): clients, jobs, invoices, payments,
+assets, issues, vendors, items (inventory), expenses, timesheets (jobs), bank-accounts (banking),
+bank-transactions (banking), profiles (team), kb-articles/kb-attachments/kb-article-issues (kb),
+locations, location-contacts (locations), bill-import-sessions (purchases).
+
+The full REST contract is documented in [`../openapi.yaml`](../openapi.yaml).
+
+## Example prompts
+
+- "List all active clients."
+- "How many invoices are still in `draft` status?" (list invoices, filter client-side)
+- "Create a new client named Acme Pty Ltd with email accounts@acme.example."
+- "Create a draft invoice for client `<id>` with a total of 1500."
+- "Mark invoice `<id>` as sent."
+
+## Test
+
+```sh
+npm test   # builds, then runs the api-client unit tests with node --test
+```
+
+The tests cover URL normalization and the actionable error-message mapping (no network calls).
+
+## Notes / limitations
+
+- The list endpoint returns at most 100 rows and supports no server-side filtering or
+  pagination — retrieve the set and filter client-side.
+- `get_record` returns `null` (not an error) when no record matches the id.