@arcforgelabs/flow 2026.10.24 → 2026.10.26

package/README.md

@@ -1,6 +1,6 @@
 # Flow
 
-Flow is invoicing, bill approval and a financial dashboard for labs that make
+Flow is job management, invoicing, bill approval and a financial dashboard for labs that make
 work to order, first for dental labs. Seazona (the lab's case system) is a
 bundled integration, and Xero is an optional one. See `VISION.md`.
 
@@ -33,6 +33,7 @@ run a lab.
 | `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
 | `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
 | `docs/DATA_SPINE.md` | The design of the tables and jobs every integration shares: mirror, identity map, job queue, outbox, review queue |
+| `docs/JOB_INVOICE_LINKS.md` | The pipeline: how each job links to its customer and to the accounting invoice that bills it |
 | `docs/RELEASING.md` | Versions and channels, the release workflows, how to cut and roll back a release, and the one-time setup |
 | `docs/SELF_HOSTING.md` | Running a Flow release with Docker, Node or Replit, the update notice, and Clerk sign-in |
 | `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |

package/VISION.md

@@ -1,21 +1,24 @@
 # Flow — Vision
 
-Flow is invoicing, bill approval and a financial dashboard for a lab that
-makes work to order, first for dental labs. It is a complete application with
-its own database. It is not a sync engine between other products.
-
-It is for the person who bills the work and pays the suppliers. Finished feels
-like this: completed cases become invoices they check and send, supplier bills
-are reviewed and approved, and one dashboard shows cash, what is owed to the
-lab, what the lab owes, and the GST for the BAS period. Every invoice a
-customer was sent can be found again, exactly as it was sent.
+Flow is job management, invoicing, bill approval and a financial dashboard
+for a lab that makes work to order, first for dental labs. It is a complete
+application with its own database. It is not a sync engine between other
+products.
+
+It is for the lab manager, the staff who move the work, and the person who
+bills it and pays the suppliers. Finished feels like this: Flow opens on a
+job board that shows every job by stage, with due dates and late jobs marked;
+completed jobs become invoices they check and send; supplier bills are
+reviewed and approved; and one dashboard shows cash, what is owed to the lab,
+what the lab owes, and the GST for the BAS period. Every invoice a customer
+was sent can be found again, exactly as it was sent.
 
 Flow is open source so any lab can run its own installation.
 
 ## The core and its integrations
 
-The core is invoices, bills, payments, credit notes, contacts, the price list,
-the jobs it bills, approvals and the dashboard. The core holds its own copy of
+The core is jobs and the job board, invoices, bills, payments, credit notes,
+contacts, the price list, approvals and the dashboard. The core holds its own copy of
 every record it shows, so it works with no integration connected and an owner
 can build reports and features on its data.
 
@@ -33,6 +36,39 @@ data spine (`docs/DATA_SPINE.md`): its records come into a mirror, get a Flow
 identity, and become core records; Flow's writes leave through an outbox; a
 conflict goes to one review queue; one job queue runs the work.
 
+## Job management
+
+Flow links each job to its client and its invoice. That link is the heart
+of the product: a job card shows what was ordered, who it is for, and how it
+was billed and paid.
+
+Flow does a few parts of job management well now, and more later. It does
+not try to replace the lab's case system.
+
+- **Now:** update job cards and process a job's information for invoicing,
+  and update jobs from paper forms.
+- **Later:** full job management.
+
+The job board is Flow's main view: a standard board of jobs by stage (a
+column per stage, a card per job), with a list view of the same jobs. It
+shows every job from the case system and from Flow, with its practice, due
+date and department. Lab staff and the manager work from it.
+
+Two parts follow the board (#48):
+
+- **An intake reader.** A photo, a form or a note becomes a proposed job
+  action: update a job, create one, or add a note. A handwriting reader and a
+  low-cost decision model propose it; a person confirms it. Nothing changes
+  until a person accepts. The model steps are optional and cost money per
+  page, so the manager sees the month's cost.
+- **A practice portal.** Practice staff sign in to follow their own jobs,
+  on desktop first, with a simpler view on phones. The server limits each
+  person to their practice.
+
+Job management is a bundled module, built the same way as the integrations,
+and a lab can remove it. Where the case system cannot take a change through
+its API, the change becomes a short checklist for a person (#49).
+
 ## Standing decisions
 
 ### Why does Flow keep its own records?
@@ -58,7 +94,10 @@ not the product.
 The case system, Flow and the accounting system each own their own records,
 and the data moves both ways. Flow records which system each change came
 from. When two systems disagree, Flow never overwrites one silently: it opens
-an item in the review queue for a person.
+an alert in the review queue. The alert shows each system's value and writes
+nothing. A person fixes the record where they choose, then presses
+**Resolved, re-check**: Flow checks that one difference again, and the alert
+closes only when the systems agree.
 
 ### Why are approvals in Flow?
 
@@ -76,7 +115,8 @@ version; the sent one stays as it was, attributed to whoever sent it.
 Dental cases carry health information, which Australian privacy law treats as
 sensitive. Flow keeps the case number and the practice. It keeps a patient
 reference only when a practice needs one printed on its invoice, and it keeps
-no clinical notes or images.
+no clinical notes or images. A form photo the intake reader reads is not kept
+after its job is updated.
 
 ### Why does Flow keep its records in PostgreSQL only?
 
@@ -94,8 +134,9 @@ its own data, configuration and secrets.
 
 ## Out of scope
 
-- Case management, production tracking and scheduling. The case system owns
-  the case.
+- Replacing the case system, for now. The case system owns the case record.
+  Flow's job board shows and updates the work, and does not do clinical
+  case management or production scheduling.
 - Patient records, clinical notes, scans and images.
 - Acting as the general ledger. Accounting software owns the ledger and the
   bank feed.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.24",
+  "version": "2026.10.26",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.24",
+      "version": "2026.10.26",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",
@@ -19,6 +19,7 @@
         "@fontsource-variable/lora": "5.3.0",
         "@fontsource-variable/nunito-sans": "5.3.0",
         "@fontsource-variable/playfair-display": "5.3.0",
+        "@fontsource-variable/plus-jakarta-sans": "5.3.0",
         "@fontsource-variable/space-grotesk": "5.3.0",
         "drizzle-orm": "0.45.3",
         "express": "5.3.0",
@@ -630,6 +631,15 @@
         "url": "https://github.com/sponsors/ayuhito"
       }
     },
+    "node_modules/@fontsource-variable/plus-jakarta-sans": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/plus-jakarta-sans/-/plus-jakarta-sans-5.3.0.tgz",
+      "integrity": "sha512-/l/4r0yyWK9JzAlmA0LiYgGgmJe/Gswt4jTJEzr5QhJfwMbvJZDmYWyW0M4X7yCK69BajMVlV/Lx8g7WDc1+sw==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
     "node_modules/@fontsource-variable/space-grotesk": {
       "version": "5.3.0",
       "resolved": "https://registry.npmjs.org/@fontsource-variable/space-grotesk/-/space-grotesk-5.3.0.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.24",
+  "version": "2026.10.26",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
   "scripts": {
     "start": "node server/index.js",
     "test": "node --test --test-concurrency=1 test/*.test.js",
+    "theme:contrast": "node scripts/theme-contrast.mjs",
     "db:generate": "drizzle-kit generate"
   },
   "dependencies": {
@@ -44,6 +45,7 @@
     "@fontsource-variable/lora": "5.3.0",
     "@fontsource-variable/nunito-sans": "5.3.0",
     "@fontsource-variable/playfair-display": "5.3.0",
+    "@fontsource-variable/plus-jakarta-sans": "5.3.0",
     "@fontsource-variable/space-grotesk": "5.3.0",
     "drizzle-orm": "0.45.3",
     "express": "5.3.0",

package/server/api/invoicing.js

@@ -0,0 +1,375 @@
+import { and, asc, desc, eq, ilike, inArray, isNull, or, sql } from 'drizzle-orm';
+import express from 'express';
+import { FlowError } from '../core/errors.js';
+import {
+  createDraftInvoice, getInvoice, issueInvoice, listInvoiceVersions, reviseInvoice, updateDraftInvoice, voidInvoice,
+} from '../core/invoices.js';
+import { draftInvoiceForObligation, listObligations } from '../core/ledger.js';
+import {
+  billingObligations, contacts, invoices, INVOICE_STATUSES, organisations, priceItems, TAX_CODES,
+} from '../db/schema.js';
+
+// Invoicing for people signed in to Flow, mounted at /api/invoicing. The web
+// UI's invoices, customers, price list and jobs pages read and write here.
+//
+//   GET   /context                    the organisations, and whether this person may issue
+//   GET   /invoices?organisationId=&status=&q=&limit=   newest first, with counts by status
+//   GET   /invoices/:id               one invoice: lines, contact, job, issued versions
+//   POST  /invoices                   a new draft
+//   PATCH /invoices/:id               change a draft
+//   POST  /invoices/:id/issue         owner or admin: number it and keep the document as sent
+//   POST  /invoices/:id/revise        owner or admin: an issued invoice back to a draft
+//   POST  /invoices/:id/void          owner or admin
+//   GET   /contacts?q=&limit=         customers, by name
+//   GET   /price-items?q=             the price list, by code
+//   GET   /jobs?view=&limit=          billable jobs (the obligation ledger), with counts by view
+//   POST  /jobs/:id/draft             owner or admin: a job's draft invoice, after a live
+//                                     check that the accounting system holds none
+//
+// Every route needs a signed-in, active person; reading and drafting are open
+// to every role. `organisationId` (query or body) names the organisation; it
+// may be left out while the installation has exactly one. Money is integer
+// cents. `liveCheckFor(organisationId)` returns the ledger's live check for
+// that organisation, or null when no accounting integration offers one.
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const VIEWS = ['ready', 'pending', 'drafted', 'invoiced', 'paid', 'held', 'review_required'];
+const MAX_LINES = 200;
+const MAX_TEXT = 500;
+// Each line's amount must fit the database's integer columns with room for
+// the invoice total.
+const MAX_QUANTITY = 100_000;
+const MAX_UNIT_CENTS = 100_000_000;
+
+const ERROR_STATUS = {
+  invalid: 400, organisation_required: 400, not_found: 404, not_draft: 409, not_issued: 409,
+  never_issued: 409, not_ready: 409, live_check_unavailable: 409,
+};
+
+function sendError(res, error, log) {
+  // A value PostgreSQL refuses (a number out of range, a date that does not
+  // exist) is the caller's mistake, not a server fault.
+  const pgCode = error.code ?? error.cause?.code;
+  if (!(error instanceof FlowError) && ['22003', '22008', '22007', '22P02'].includes(pgCode)) {
+    return res.status(400).json({ ok: false, code: 'invalid', error: 'a value is out of range or not valid' });
+  }
+  if (!(error instanceof FlowError)) {
+    log.error?.(`[invoicing] ${error.message}`);
+    return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+  }
+  const body = { ok: false, code: error.code, error: error.message };
+  if (error.details !== undefined) body.details = error.details;
+  return res.status(error.status ?? ERROR_STATUS[error.code] ?? 400).json(body);
+}
+
+const handle = (log, fn) => async (req, res) => {
+  try {
+    await fn(req, res);
+  } catch (error) {
+    sendError(res, error, log);
+  }
+};
+
+const invalid = (message) => new FlowError('invalid', message);
+const text = (raw) => (typeof raw === 'string' ? raw.trim() : '');
+const pathId = (raw, what) => {
+  if (!UUID.test(raw ?? '')) throw new FlowError('not_found', `${what} not found`);
+  return raw;
+};
+
+function limitOf(raw, fallback, max) {
+  if (raw === undefined) return fallback;
+  const n = Number(text(raw));
+  if (!Number.isInteger(n) || n < 1) throw invalid(`limit must be a whole number from 1 to ${max}`);
+  return Math.min(n, max);
+}
+
+// A LIKE pattern that matches the text anywhere, with its wildcards escaped.
+const containing = (q) => `%${q.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+
+function isRealDate(value) {
+  if (!DATE.test(value)) return false;
+  const d = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+
+function optionalText(raw, name) {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw !== 'string') throw invalid(`${name} must be text`);
+  if (raw.length > MAX_TEXT) throw invalid(`${name} is too long (${MAX_TEXT} characters at most)`);
+  return raw.trim() || null;
+}
+
+function optionalDate(raw, name) {
+  if (raw === undefined || raw === null || raw === '') return null;
+  if (typeof raw !== 'string' || !isRealDate(raw)) throw invalid(`${name} must be a date, YYYY-MM-DD`);
+  return raw;
+}
+
+function requireBodyId(raw, name) {
+  if (typeof raw !== 'string' || !UUID.test(raw)) throw invalid(`${name} must be a Flow id`);
+  return raw;
+}
+
+function readLines(raw) {
+  if (!Array.isArray(raw)) throw invalid('lines must be a list');
+  if (raw.length > MAX_LINES) throw invalid(`an invoice has ${MAX_LINES} lines at most`);
+  return raw.map((line, index) => {
+    const at = `line ${index + 1}`;
+    if (!line || typeof line !== 'object' || Array.isArray(line)) throw invalid(`${at} must be an object`);
+    const out = {};
+    if (line.priceItemId !== undefined && line.priceItemId !== null) out.priceItemId = requireBodyId(line.priceItemId, `${at}: priceItemId`);
+    // A blank description takes the price item's name.
+    const description = optionalText(line.description, `${at}: description`);
+    if (description) out.description = description;
+    if (line.quantity !== undefined) {
+      if (!Number.isInteger(line.quantity) || line.quantity < 1 || line.quantity > MAX_QUANTITY) {
+        throw invalid(`${at}: quantity must be a whole number from 1 to ${MAX_QUANTITY}`);
+      }
+      out.quantity = line.quantity;
+    }
+    if (line.unitAmountCents !== undefined && line.unitAmountCents !== null) {
+      if (!Number.isInteger(line.unitAmountCents) || Math.abs(line.unitAmountCents) > MAX_UNIT_CENTS) {
+        throw invalid(`${at}: unitAmountCents must be whole cents`);
+      }
+      out.unitAmountCents = line.unitAmountCents;
+    }
+    if (line.taxCode !== undefined && line.taxCode !== null) {
+      if (!TAX_CODES.includes(line.taxCode)) throw invalid(`${at}: taxCode must be one of ${TAX_CODES.join(', ')}`);
+      out.taxCode = line.taxCode;
+    }
+    return out;
+  });
+}
+
+// The server's own calendar date.
+function today() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// The organisation a request is about: the one it names, or the only one.
+export async function resolveOrganisation(db, raw) {
+  if (raw !== undefined && raw !== null && raw !== '') {
+    const organisationId = text(raw);
+    if (!UUID.test(organisationId)) throw invalid('organisationId must be a Flow organisation id');
+    const [row] = await db.select({ id: organisations.id }).from(organisations).where(eq(organisations.id, organisationId));
+    if (!row) throw new FlowError('not_found', 'organisation not found');
+    return organisationId;
+  }
+  const rows = await db.select({ id: organisations.id }).from(organisations).limit(2);
+  if (rows.length === 1) return rows[0].id;
+  throw new FlowError('organisation_required', rows.length
+    ? 'This installation has more than one organisation: say which one (organisationId).'
+    : 'This installation has no organisation yet.');
+}
+
+const jobOf = (o) => (o ? {
+  id: o.id, sourceSystem: o.sourceSystem, sourceJobRef: o.sourceJobRef, caseRef: o.caseRef, practitioner: o.practitioner, shippedOn: o.shippedOn,
+} : null);
+
+async function jobsByInvoice(db, organisationId, invoiceIds) {
+  if (!invoiceIds.length) return new Map();
+  const rows = await db.select().from(billingObligations)
+    .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, invoiceIds)));
+  return new Map(rows.map((o) => [o.invoiceId, jobOf(o)]));
+}
+
+async function invoiceDetail(db, organisationId, invoiceId) {
+  const invoice = await getInvoice(db, organisationId, invoiceId);
+  const [[contact], versions, jobs] = await Promise.all([
+    db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
+      .where(and(eq(contacts.organisationId, organisationId), eq(contacts.id, invoice.contactId))),
+    listInvoiceVersions(db, organisationId, invoiceId),
+    jobsByInvoice(db, organisationId, [invoiceId]),
+  ]);
+  return {
+    ...invoice,
+    contact: contact ?? null,
+    job: jobs.get(invoiceId) ?? null,
+    versions: versions.map(({ version, issuedAt, issuedBy }) => ({ version, issuedAt, issuedBy })),
+  };
+}
+
+export function createInvoicingRouter({ db, personAuth, log = console, liveCheckFor = () => null }) {
+  const router = express.Router();
+  router.use(express.json({ limit: '64kb' }));
+
+  const signedIn = [personAuth.requireSession];
+  const manager = [...signedIn, personAuth.requireRole('owner', 'admin')];
+  const organisationOf = (req) => resolveOrganisation(db, req.method === 'GET' ? req.query.organisationId : (req.body?.organisationId ?? req.query.organisationId));
+
+  router.get('/context', ...signedIn, handle(log, async (req, res) => {
+    const rows = await db.select({
+      id: organisations.id, name: organisations.name, invoicePrefix: organisations.invoicePrefix, nextInvoiceNumber: organisations.nextInvoiceNumber,
+    }).from(organisations).orderBy(asc(organisations.name));
+    res.json({ ok: true, organisations: rows, canIssue: ['owner', 'admin'].includes(req.person.role) });
+  }));
+
+  router.get('/invoices', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const status = text(req.query.status);
+    if (status && !INVOICE_STATUSES.includes(status)) throw invalid(`status must be one of ${INVOICE_STATUSES.join(', ')}`);
+    const q = text(req.query.q);
+    const limit = limitOf(req.query.limit, 200, 500);
+    const where = [eq(invoices.organisationId, organisationId)];
+    if (status) where.push(eq(invoices.status, status));
+    if (q) {
+      const pattern = containing(q);
+      where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
+    }
+    const rows = await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+      .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+      .where(and(...where))
+      .orderBy(desc(invoices.createdAt), desc(invoices.id))
+      .limit(limit);
+    const jobs = await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id));
+    const counted = await db.select({ status: invoices.status, n: sql`count(*)::int` }).from(invoices)
+      .where(eq(invoices.organisationId, organisationId)).groupBy(invoices.status);
+    const counts = Object.fromEntries(INVOICE_STATUSES.map((s) => [s, 0]));
+    for (const { status: s, n } of counted) counts[s] = n;
+    res.json({
+      ok: true,
+      invoices: rows.map(({ invoice, contactName }) => ({ ...invoice, contactName, job: jobs.get(invoice.id) ?? null })),
+      counts,
+    });
+  }));
+
+  router.get('/invoices/:id', ...signedIn, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const body = req.body ?? {};
+    const draft = await createDraftInvoice(db, organisationId, {
+      contactId: requireBodyId(body.contactId, 'contactId'),
+      reference: optionalText(body.reference, 'reference'),
+      dueDate: optionalDate(body.dueDate, 'dueDate'),
+      lines: body.lines === undefined ? [] : readLines(body.lines),
+    });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} made draft invoice ${draft.id}`);
+    res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, draft.id) });
+  }));
+
+  router.patch('/invoices/:id', ...signedIn, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    const body = req.body ?? {};
+    const changes = {};
+    if (body.contactId !== undefined) changes.contactId = requireBodyId(body.contactId, 'contactId');
+    if (body.reference !== undefined) changes.reference = optionalText(body.reference, 'reference');
+    if (body.dueDate !== undefined) changes.dueDate = optionalDate(body.dueDate, 'dueDate');
+    if (body.lines !== undefined) changes.lines = readLines(body.lines);
+    if (!Object.keys(changes).length) throw invalid('nothing to change: send contactId, reference, dueDate or lines');
+    await updateDraftInvoice(db, organisationId, invoiceId, changes);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices/:id/issue', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    const issueDate = optionalDate(req.body?.issueDate, 'issueDate') ?? today();
+    const issued = await issueInvoice(db, organisationId, invoiceId, { issuedBy: `person:${req.person.id}`, issueDate });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} issued invoice ${issued.number} (version ${issued.issuedVersion})`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices/:id/revise', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    await reviseInvoice(db, organisationId, invoiceId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} opened invoice ${invoiceId} for revision`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.post('/invoices/:id/void', ...manager, handle(log, async (req, res) => {
+    const invoiceId = pathId(req.params.id, 'invoice');
+    const organisationId = await organisationOf(req);
+    await voidInvoice(db, organisationId, invoiceId);
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} voided invoice ${invoiceId}`);
+    res.json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoiceId) });
+  }));
+
+  router.get('/contacts', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const q = text(req.query.q);
+    const where = [eq(contacts.organisationId, organisationId), eq(contacts.kind, 'customer')];
+    if (q) where.push(ilike(contacts.name, containing(q)));
+    const rows = await db.select({ id: contacts.id, name: contacts.name, email: contacts.email }).from(contacts)
+      .where(and(...where)).orderBy(asc(contacts.name), asc(contacts.id)).limit(limitOf(req.query.limit, 50, 500));
+    res.json({ ok: true, contacts: rows });
+  }));
+
+  router.get('/price-items', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const q = text(req.query.q);
+    const where = [eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)];
+    if (q) where.push(or(ilike(priceItems.code, containing(q)), ilike(priceItems.name, containing(q))));
+    const rows = await db.select({
+      id: priceItems.id, code: priceItems.code, name: priceItems.name, unitAmountCents: priceItems.unitAmountCents, taxCode: priceItems.taxCode,
+    }).from(priceItems).where(and(...where)).orderBy(asc(priceItems.code));
+    res.json({ ok: true, priceItems: rows });
+  }));
+
+  router.get('/jobs', ...signedIn, handle(log, async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const view = text(req.query.view);
+    if (view && !VIEWS.includes(view)) throw invalid(`view must be one of ${VIEWS.join(', ')}`);
+    const limit = limitOf(req.query.limit, 200, 500);
+    const all = await listObligations(db, organisationId);
+    const counts = Object.fromEntries(VIEWS.map((v) => [v, 0]));
+    for (const entry of all) counts[entry.view] += 1;
+    const listed = (view ? all.filter((entry) => entry.view === view) : all).slice(0, limit);
+    const contactIds = [...new Set(listed.map((e) => e.obligation.contactId).filter(Boolean))];
+    const invoiceIds = [...new Set(listed.map((e) => e.obligation.invoiceId).filter(Boolean))];
+    const [names, numbers] = await Promise.all([
+      contactIds.length
+        ? db.select({ id: contacts.id, name: contacts.name }).from(contacts)
+          .where(and(eq(contacts.organisationId, organisationId), inArray(contacts.id, contactIds)))
+        : [],
+      invoiceIds.length
+        ? db.select({ id: invoices.id, number: invoices.number, status: invoices.status }).from(invoices)
+          .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, invoiceIds)))
+        : [],
+    ]);
+    const nameOf = new Map(names.map((c) => [c.id, c.name]));
+    const invoiceOf = new Map(numbers.map((i) => [i.id, i]));
+    res.json({
+      ok: true,
+      jobs: listed.map(({ obligation: { lineFingerprint: _fingerprint, organisationId: _org, ...o }, view: v, reasons }) => ({
+        ...o,
+        contactName: nameOf.get(o.contactId) ?? null,
+        invoiceNumber: invoiceOf.get(o.invoiceId)?.number ?? null,
+        invoiceStatus: invoiceOf.get(o.invoiceId)?.status ?? null,
+        view: v,
+        reasons,
+      })),
+      counts,
+    });
+  }));
+
+  router.post('/jobs/:id/draft', ...manager, handle(log, async (req, res) => {
+    const obligationId = pathId(req.params.id, 'job');
+    const organisationId = await organisationOf(req);
+    const liveCheck = liveCheckFor(organisationId);
+    if (typeof liveCheck !== 'function') {
+      throw new FlowError('live_check_unavailable', 'Flow drafts a job\'s invoice only after checking that the accounting system holds none for it. Turn on and connect Xero first.');
+    }
+    const { invoice } = await draftInvoiceForObligation(db, organisationId, obligationId, { liveCheck, actor: `person:${req.person.id}` });
+    log.info?.(`[invoicing] organisation ${organisationId}: person ${req.person.id} drafted invoice ${invoice.id} from job ${obligationId}`);
+    res.status(201).json({ ok: true, invoice: await invoiceDetail(db, organisationId, invoice.id) });
+  }));
+
+  // A body that is not JSON, or too large, answers like every other refusal.
+  router.use((error, _req, res, next) => {
+    if (error?.type === 'entity.too.large') return res.status(413).json({ ok: false, code: 'too_large', error: 'The request body is too large.' });
+    if (error?.status === 400 || error?.type === 'entity.parse.failed') return res.status(400).json({ ok: false, code: 'invalid', error: 'The request body must be JSON.' });
+    return next(error);
+  });
+
+  return router;
+}

package/server/app.js

@@ -1,5 +1,6 @@
 import express from 'express';
 import { createConnectorApi } from './api/connector.js';
+import { createInvoicingRouter } from './api/invoicing.js';
 import { createSignInRouter } from './auth/routes.js';
 import { deployedBuildStatus } from './deployed-build.js';
 import { integrationsHealth } from './integrations/health.js';
@@ -100,6 +101,16 @@ export function createApp({
   if (integrations && database && auth?.personAuth) {
     app.use('/api/integrations', createSetupRouter({ db: database.db, registry: integrations, personAuth: auth.personAuth, secrets, log }));
   }
+  // Invoicing for signed-in people (server/api/invoicing.js). A job's draft
+  // invoice needs a live check in the accounting system: the first enabled
+  // integration that offers `checkInvoice` (Xero) answers it.
+  if (database && auth?.personAuth) {
+    const liveCheckFor = (organisationId) => {
+      const [adapter] = integrations?.with('checkInvoice') ?? [];
+      return adapter ? (obligation) => adapter.capabilities.checkInvoice({ organisationId, obligation }) : null;
+    };
+    app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor }));
+  }
   for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log, messagePage: page }) ?? []) {
     app.use(path, handler);
   }

package/server/auth/people.js

@@ -1,6 +1,7 @@
 import { and, asc, eq, isNull, ne, sql } from 'drizzle-orm';
 import { people, PERSON_ROLES } from '../db/schema.js';
 import { FlowError } from '../core/errors.js';
+import { isThemeFamily, normalizeAccent } from '../theme/themes.js';
 import { isPlainEmail } from './settings.js';
 
 // The people who may sign in, and their roles. Only an owner changes this
@@ -24,6 +25,31 @@ export function publicPerson(row) {
   };
 }
 
+const COLOR_MODES = ['light', 'dark', 'system'];
+
+// A person's appearance as Flow stores it: only the known keys, each checked.
+// A family Flow does not have, or a malformed accent, is dropped, so the page
+// falls back to the installation's default.
+export function normaliseAppearance(input) {
+  const value = input && typeof input === 'object' ? input : {};
+  const out = { colorMode: COLOR_MODES.includes(value.colorMode) ? value.colorMode : 'system' };
+  if (isThemeFamily(value.themeFamily)) out.themeFamily = value.themeFamily;
+  const accent = typeof value.accent === 'string' ? value.accent.trim().toLowerCase() : '';
+  if (normalizeAccent(accent)) out.accent = accent;
+  return out;
+}
+
+// Each person keeps their own appearance, so people who share a browser or
+// move between devices each see theirs.
+export async function setPersonAppearance(db, { id, appearance }) {
+  const [row] = await db.update(people)
+    .set({ appearance: normaliseAppearance(appearance), updatedAt: new Date() })
+    .where(eq(people.id, id))
+    .returning();
+  if (!row) throw new FlowError('not_found', 'person not found');
+  return row.appearance;
+}
+
 export async function findPersonById(db, id) {
   const [row] = await db.select().from(people).where(eq(people.id, id));
   return row ?? null;

package/server/auth/routes.js

@@ -7,8 +7,10 @@ import {
   invitePerson,
   listPeople,
   normaliseEmail,
+  normaliseAppearance,
   publicPerson,
   removePerson,
+  setPersonAppearance,
   updatePerson,
 } from './people.js';
 import { isPlainEmail } from './settings.js';
@@ -96,9 +98,20 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
       const check = await ownerVerification(req.person, req.clerkAuth);
       body.ownerActions = { allowed: Boolean(check.verified), by: check.by ?? null };
     }
+    body.appearance = req.person.appearance ? normaliseAppearance(req.person.appearance) : null;
     res.json(body);
   });
 
+  // Each person sets their own appearance; it follows their account.
+  router.put('/api/me/appearance', requireSession, express.json({ limit: '4kb' }), async (req, res) => {
+    try {
+      const appearance = await setPersonAppearance(db, { id: req.person.id, appearance: req.body });
+      res.json({ ok: true, appearance });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
   // Only an owner manages people.
   const people = express.Router();
   people.use(requireSession, requireOwner, express.json({ limit: '16kb' }));