feat: clinic-wide AI (analytics/earnings/inventory + invoice-from-file),

real Live card, persistent chat history

Analytics & earnings:
- Analytics now carries real money computed from invoices (billed/paid/
  outstanding + by-month); new Earnings section on the Analysis page drawn with
  the project's Bklit chart components (shared EarningsChart).

AI agent reaches the whole clinic:
- new read tools getClinicInfo / getAnalytics / listInventory render clinic,
  analytics (with a Bklit earnings chart) and inventory cards in chat
- proposeInvoice turns an uploaded purchase/medication list into an invoice
  (new "invoice" action-preview kind → createInvoice); invoices/appointments
  auto-create/link a patient (ensurePatient) so they hit the Patients page

Live card:
- plots real data — patients checked in today — via GET /api/analytics/live
  (polled); value pill clamped and margins widened so nothing spills the card

Persistent AI chat history (Claude-style):
- ai_chat_threads + ai_chat_messages (migration 0016); per-user, org-scoped
  thread CRUD under /api/chat/threads
- chat panel owns a thread id, loads /?thread=<id>, and auto-saves after each
  exchange; sidebar lists past chats (open/delete), "New chat" starts fresh

Verified with backend typecheck + frontend tsc + next build.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/src/services/ai-chat.ts

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+
+import { and, asc, desc, eq } from "drizzle-orm";
+
+import { db } from "../db/index.js";
+import { aiChatMessages, aiChatThreads } from "../db/schema/ai-chat.js";
+import { HttpError } from "../lib/http-error.js";
+
+export type StoredMessage = { role: string; parts: unknown };
+
+export type ThreadSummary = {
+  id: string;
+  title: string;
+  updatedAt: string;
+};
+
+export async function listThreads(
+  orgId: string,
+  userId: string,
+): Promise<ThreadSummary[]> {
+  const rows = await db
+    .select({
+      id: aiChatThreads.id,
+      title: aiChatThreads.title,
+      updatedAt: aiChatThreads.updatedAt,
+    })
+    .from(aiChatThreads)
+    .where(
+      and(
+        eq(aiChatThreads.organizationId, orgId),
+        eq(aiChatThreads.userId, userId),
+      ),
+    )
+    .orderBy(desc(aiChatThreads.updatedAt))
+    .limit(50);
+  return rows.map((r) => ({
+    id: r.id,
+    title: r.title,
+    updatedAt: r.updatedAt.toISOString(),
+  }));
+}
+
+export async function getThread(
+  orgId: string,
+  userId: string,
+  threadId: string,
+): Promise<{ id: string; title: string; messages: StoredMessage[] } | null> {
+  const [thread] = await db
+    .select()
+    .from(aiChatThreads)
+    .where(
+      and(
+        eq(aiChatThreads.id, threadId),
+        eq(aiChatThreads.organizationId, orgId),
+        eq(aiChatThreads.userId, userId),
+      ),
+    );
+  if (!thread) return null;
+  const rows = await db
+    .select({ role: aiChatMessages.role, parts: aiChatMessages.parts })
+    .from(aiChatMessages)
+    .where(eq(aiChatMessages.threadId, threadId))
+    .orderBy(asc(aiChatMessages.position));
+  return {
+    id: thread.id,
+    title: thread.title,
+    messages: rows.map((r) => ({ role: r.role, parts: r.parts })),
+  };
+}
+
+// Upsert a thread and replace its messages with the supplied snapshot. The
+// thread id is client-generated; ownership is enforced (you can only write your
+// own threads within your clinic).
+export async function saveThread(
+  orgId: string,
+  userId: string,
+  threadId: string,
+  messages: StoredMessage[],
+  title: string,
+): Promise<void> {
+  await db.transaction(async (tx) => {
+    const [existing] = await tx
+      .select({ userId: aiChatThreads.userId })
+      .from(aiChatThreads)
+      .where(eq(aiChatThreads.id, threadId));
+    if (existing && existing.userId !== userId) {
+      throw new HttpError(403, "Not your conversation.");
+    }
+    if (existing) {
+      await tx
+        .update(aiChatThreads)
+        .set({ title, updatedAt: new Date() })
+        .where(eq(aiChatThreads.id, threadId));
+      await tx
+        .delete(aiChatMessages)
+        .where(eq(aiChatMessages.threadId, threadId));
+    } else {
+      await tx
+        .insert(aiChatThreads)
+        .values({ id: threadId, organizationId: orgId, userId, title });
+    }
+    if (messages.length > 0) {
+      await tx.insert(aiChatMessages).values(
+        messages.map((m, i) => ({
+          id: randomUUID(),
+          threadId,
+          position: i,
+          role: m.role,
+          parts: m.parts,
+        })),
+      );
+    }
+  });
+}
+
+export async function deleteThread(
+  orgId: string,
+  userId: string,
+  threadId: string,
+): Promise<boolean> {
+  const deleted = await db
+    .delete(aiChatThreads)
+    .where(
+      and(
+        eq(aiChatThreads.id, threadId),
+        eq(aiChatThreads.organizationId, orgId),
+        eq(aiChatThreads.userId, userId),
+      ),
+    )
+    .returning({ id: aiChatThreads.id });
+  return deleted.length > 0;
+}

backend/src/services/ai/tools.ts

@@ -2,11 +2,19 @@ import { tool } from "ai";
 import type { UIMessageStreamWriter } from "ai";
 import { z } from "zod";
 
+import { eq } from "drizzle-orm";
+
+import { db } from "../../db/index.js";
+import { organization } from "../../db/schema/auth.js";
 import { appointmentInputSchema } from "../../lib/appointment-validation.js";
+import { initialsFromName } from "../../lib/initials.js";
+import { invoiceInputSchema } from "../../lib/invoice-validation.js";
 import { patientInputSchema } from "../../lib/patient-validation.js";
 import { prescriptionInputSchema } from "../../lib/prescription-validation.js";
 import { taskInputSchema } from "../../lib/task-validation.js";
+import * as analytics from "../analytics.js";
 import * as appointments from "../appointments.js";
+import * as inventory from "../inventory.js";
 import * as patients from "../patients.js";
 import * as prescriptions from "../prescriptions.js";
 import * as tasks from "../tasks.js";
@@ -407,6 +415,123 @@ export function createChatTools(ctx: ToolContext) {
       },
     }),
 
+    // --- Clinic-wide reads (aggregates / non-PHI — safe to return to model) ---
+
+    getClinicInfo: tool({
+      description:
+        "Get the clinic's name and basic info. Use when the clinician asks about their clinic/organization (e.g. 'what's my clinic called?').",
+      inputSchema: z.object({}),
+      execute: async () => {
+        step("Loading clinic info");
+        const [org] = await db
+          .select({
+            name: organization.name,
+            slug: organization.slug,
+            createdAt: organization.createdAt,
+          })
+          .from(organization)
+          .where(eq(organization.id, orgId));
+        const info = {
+          name: org?.name ?? "",
+          slug: org?.slug ?? null,
+          createdAt: org?.createdAt ? org.createdAt.toISOString() : null,
+        };
+        writer.write({ type: "data-clinicCard", data: info });
+        return info;
+      },
+    }),
+
+    getAnalytics: tool({
+      description:
+        "Retrieve the clinic's analytics AND earnings — patient/appointment/prescription/task counts plus money billed, paid, and outstanding (from invoices), with a by-month earnings trend. Use for KPIs, earnings, revenue, or performance questions.",
+      inputSchema: z.object({}),
+      execute: async () => {
+        step("Loading clinic analytics");
+        const data = await analytics.getAnalytics(orgId);
+        writer.write({ type: "data-analyticsCard", data });
+        return data; // aggregates only, no PHI
+      },
+    }),
+
+    listInventory: tool({
+      description:
+        "List the clinic's inventory (medications/supplies, stock levels, reorder thresholds). Use for stock, low-stock, or reorder questions.",
+      inputSchema: z.object({}),
+      execute: async () => {
+        step("Loading inventory");
+        const items = await inventory.listInventory(orgId);
+        writer.write({ type: "data-inventoryList", data: { items } });
+        return {
+          count: items.length,
+          items: items.map((i) => ({
+            name: i.name,
+            form: i.form,
+            strength: i.strength,
+            stock: i.stockQuantity,
+            reorderThreshold: i.reorderThreshold,
+          })),
+        };
+      },
+    }),
+
+    proposeInvoice: tool({
+      description:
+        "Propose a new invoice for the clinician to approve — e.g. parse an uploaded list of purchased medications into billable line items. Does NOT save; it shows an approval card the clinician confirms. Provide the patient/client name (a file number if known) and line items {description, quantity, unitPrice}; prices come from the uploaded document.",
+      inputSchema: z.object({
+        name: z.string().describe("Patient/client name (may be a token)"),
+        fileNumber: z
+          .string()
+          .optional()
+          .describe("Patient file number / MRN if known"),
+        lineItems: z
+          .array(
+            z.object({
+              description: z.string(),
+              quantity: z.number(),
+              unitPrice: z.number(),
+            }),
+          )
+          .describe("Billed items, e.g. each purchased medication"),
+        notes: z.string().nullish(),
+      }),
+      execute: async ({ name, fileNumber, lineItems, notes }) => {
+        step(`Drafting invoice for ${fileNumber ?? name}`);
+        const patient = fileNumber ? await resolvePatient(fileNumber) : null;
+        const resolvedName = patient?.name ?? (name ? veil.rehydrate(name) : "");
+        if (!resolvedName) {
+          return { ok: false as const, reason: "patient_not_found" as const };
+        }
+        const candidate = {
+          fileNumber: patient?.fileNumber ?? "",
+          name: resolvedName,
+          initials: patient?.initials ?? initialsFromName(resolvedName),
+          lineItems,
+          notes: notes ?? null,
+          source: "ai" as const,
+        };
+        const parsed = invoiceInputSchema.safeParse(candidate);
+        const issues = parsed.success
+          ? []
+          : parsed.error.issues.map(
+              (i) => `${i.path.join(".") || "(root)"}: ${i.message}`,
+            );
+        writer.write({
+          type: "data-actionPreview",
+          data: {
+            token: `invoice-${stepSeq}`,
+            kind: "invoice" as const,
+            record: parsed.success ? parsed.data : candidate,
+            issues,
+          },
+        });
+        return {
+          ok: parsed.success,
+          issues,
+          note: "Preview only — awaiting clinician approval before any write.",
+        };
+      },
+    }),
+
     // Migration: validate parsed records WITHOUT writing. The model parses an
     // uploaded export into our patient shape and calls this; the result drives
     // an approval card. Nothing is inserted until the clinician approves and the

backend/src/services/analytics.ts

@@ -3,10 +3,12 @@ import type { PgTable } from "drizzle-orm/pg-core";
 
 import { db } from "../db/index.js";
 import { appointments } from "../db/schema/appointments.js";
+import { invoices } from "../db/schema/invoices.js";
 import { patients } from "../db/schema/patients.js";
 import { prescriptions } from "../db/schema/prescriptions.js";
 import { tasks } from "../db/schema/tasks.js";
 import type { Analytics } from "../types/analytics.js";
+import { invoiceTotal } from "./invoices.js";
 
 const pad = (n: number) => String(n).padStart(2, "0");
 const keyOf = (d: Date) =>
@@ -178,6 +180,41 @@ export async function getAnalytics(orgId: string): Promise<Analytics> {
     count: dayCounts.get(d.key) ?? 0,
   }));
 
+  // Earnings from invoices (real money). `void` invoices are excluded entirely.
+  const invoiceRows = await db
+    .select({
+      lineItems: invoices.lineItems,
+      status: invoices.status,
+      issuedAt: invoices.issuedAt,
+    })
+    .from(invoices)
+    .where(eq(invoices.organizationId, orgId));
+  let totalBilled = 0;
+  let totalPaid = 0;
+  let totalOutstanding = 0;
+  const billedByMonth = new Map(months.map((m) => [m.key, 0]));
+  const paidByMonth = new Map(months.map((m) => [m.key, 0]));
+  for (const inv of invoiceRows) {
+    if (inv.status === "void") continue;
+    const amount = invoiceTotal({ lineItems: inv.lineItems });
+    totalBilled += amount;
+    if (inv.status === "paid") totalPaid += amount;
+    else totalOutstanding += amount; // draft + sent
+    // issuedAt is a YYYY-MM-DD string; its YYYY-MM prefix is the month key.
+    const monthKey = inv.issuedAt.slice(0, 7);
+    if (billedByMonth.has(monthKey)) {
+      billedByMonth.set(monthKey, billedByMonth.get(monthKey)! + amount);
+      if (inv.status === "paid") {
+        paidByMonth.set(monthKey, paidByMonth.get(monthKey)! + amount);
+      }
+    }
+  }
+  const earningsByMonth = months.map((m) => ({
+    label: m.label,
+    billed: billedByMonth.get(m.key) ?? 0,
+    paid: paidByMonth.get(m.key) ?? 0,
+  }));
+
   return {
     patients: {
       total: patientsTotal,
@@ -192,6 +229,26 @@ export async function getAnalytics(orgId: string): Promise<Analytics> {
     },
     prescriptions: { total: rxTotal, active: rxActive },
     tasks: { open: tasksOpen, done: tasksDone },
+    earnings: {
+      totalBilled,
+      totalPaid,
+      totalOutstanding,
+      byMonth: earningsByMonth,
+    },
     trends: { patientsByMonth, appointmentsByWeekday },
   };
 }
+
+// "In the building now" — today's appointments that are checked in. Cheap query
+// for the Analysis Live card to poll.
+export async function getLiveMetric(orgId: string): Promise<number> {
+  const todayKey = keyOf(new Date());
+  return countWhere(
+    appointments,
+    and(
+      eq(appointments.organizationId, orgId),
+      eq(appointments.date, todayKey),
+      eq(appointments.status, "checked-in"),
+    )!,
+  );
+}

backend/src/services/invoices.ts

@@ -4,6 +4,7 @@ import { db } from "../db/index.js";
 import { invoices } from "../db/schema/invoices.js";
 import type { InvoiceInput } from "../lib/invoice-validation.js";
 import type { Invoice, InvoiceInstallment } from "../types/invoice.js";
+import * as patients from "./patients.js";
 
 type InvoiceRow = typeof invoices.$inferSelect;
 
@@ -104,9 +105,17 @@ export async function createInvoice(
   input: InvoiceInput,
 ): Promise<Invoice> {
   const number = input.number || (await generateInvoiceNumber(orgId));
+  // Link to a patient — creating one when the invoice has no file number (e.g.
+  // an AI invoice built from an uploaded purchase list), so the client shows up
+  // on the Patients page.
+  const fileNumber = await patients.ensurePatient(orgId, userId, {
+    fileNumber: input.fileNumber,
+    name: input.name,
+    initials: input.initials,
+  });
   const [row] = await db
     .insert(invoices)
-    .values(columns(orgId, { ...input, number }, userId))
+    .values(columns(orgId, { ...input, number, fileNumber }, userId))
     .returning();
   return toInvoice(row!);
 }