Purpose

The bookkeeping domain's home surface: a tenant opens /accounting and sees the current fiscal year's revenue, expenses and profit, a monthly revenue-versus-expenses chart, an expense breakdown by account, the open invoices still waiting on payment, an AI-written financial summary, and four quick actions into the rest of the module, all in one screen. The invariant that makes it trustworthy: the KPI numbers, the two charts and the invoice list are all a straight read of the backend's own aggregation (GET /api/accounting/dashboard-data, computed from posted and draft journal entry lines grouped by account type) and a straight read of the invoice list (GET /api/accounting/invoices, filtered client-side to sent/overdue), never a number this page computes from something else.

It makes visible five of this wave's six backend recipes: the chart of accounts and double-entry engine that every journal line's account type is checked against (chart-of-accounts-and-double-entry-engine), the journal entries whose debit/credit lines the monthly chart and the expense breakdown are summed from (journal-entries-and-recurring-templates), the invoices the open-invoices list and the "offene Rechnungen" KPI are read from (customer-invoicing-and-qr-bill-pdf), and, indirectly, the VAT and bank-reconciliation recipes (vat-reporting-and-rates, bank-statement-import-and-reconciliation) in that their postings flow into the same journal entries this page's totals are summed from without a dedicated card of their own. financial-reports-and-ledger is named in backend_modules for the profit-and-loss read the AI insight route reuses, but the dashboard-data route this page actually calls lives beside it in the same core accounting router, not inside that recipe, a seam this recipe's Gotchas records rather than glossing over. The Finanzanalyse card's own backend, POST /api/accounting/ai-insight (a Prima-routed call), is outside this wave's six backend recipes entirely: this page renders it as a loading-shimmer/populated block and nothing more, never claiming an insight generator this wave did not ship.

When to use

Trigger phrases: "the accounting dashboard", "Voila home", "the bookkeeping overview", "my revenue and expenses", "open invoices at a glance", "the Finanzanalyse card", "Buchhaltung Uebersicht". Surface: SPA, a private Labs page behind PrivateRoute, reached at /accounting (the "Overview" item under the "Money" domain, nav.tsx line 206 to 228 at fd8558f, marked adminOnly in the navigation model only, not enforced by the route or the backend, Security and tenancy).

Not this recipe: the eight sub-pages this dashboard's quick actions and card headers link out to (/accounting/kontenplan, /buchungen, /rechnungen, /belege, /berichte, /kapital, /einstellungen, /bankabgleich, each its own component and route, App.tsx line 83 to 91 and 529 to 537), none of them rendered here; the AI insight generator itself (POST /api/accounting/ai-insight, a Prima-routed call outside this wave's six backend recipes, Purpose); and the six backend recipes this page is a window onto (backend_modules above), none of which a tenant reaches directly.

Stack assumptions

S1 tokens and S2 skeleton assumed; pinned per the source at 62ba4fc: react ^19.1.1, react-router-dom ^7.8.2, tailwindcss ^3.4.17, recharts ^3.3.0, lucide-react ^0.563.0, axios ^1.11.0. Component library: none directly. Unlike most of the rest of Labs, this file imports no @prima-modules/alchemy-ui atom at all; every card, button and badge is a hand-styled div/button from two page-local files, i18n/accounting.ts (translations, formatMoney, formatMonth) and components/accounting/shared.tsx (KpiCard, PageHeader, StatusBadge, MoneyDisplay, DataTable, AmountInput, AccountSelector, DateDisplay). rendering.design_system is still alchemy-ui here, not because this file uses its atoms, but because it renders inside Navigation = AppShell, which is alchemy-ui-based, and because the ink/ink-60/ink-40/line/purple classes this file's own markup uses are the same @prima-modules/tokens layer alchemy-ui bundles (both generated from frontend/tailwind.config.js, decision D1a); a page that never imports an atom from the library it is still built on the tokens of is itself worth a line, not silently smoothed over (Gotchas). Data-fetch style: the api singleton (S2), the Bearer header from accessToken plus X-Workspace-ID from currentWorkspaceId in localStorage (services/api.ts line 32 to 43), unlike billing-credits/ui/subscription-manager's user-only routes, this page's routes are workspace-scoped (WorkspaceID dependency, Security and tenancy). Copy language: German, de-CH, every string on the page (the AI insight text itself is server-generated German too, per its own prompt, accounting_router.py line 215 to 227).

Data model

Client state (AccountingDashboard.tsx line 50 to 54), all in the page component, nothing persisted beyond S2's tokens and currentWorkspaceId:

interface DashboardData {                          // GET /api/accounting/dashboard-data's body, unchanged
  monthly: { month: string; revenue: number; expenses: number }[];   // month as "YYYY-MM"
  expense_by_account: { name: string; value: number }[];             // top 5 by absolute value plus "Uebriges"
  kpi: {
    revenue: number; expenses: number; profit: number;
    open_invoices_count: number; open_invoices_amount: number;
    pending_review: number;                        // sourced from AccountingExpense, not this page's own read (Gotchas)
  };
  period: { start: string; end: string; fiscal_year: string } | null;  // null when the workspace has no fiscal year yet
}
dashData: DashboardData | null; insight: string; insightLoading: boolean (initially true);
dataLoading: boolean (initially true); openInvoices: Invoice[] (initially []);

The demo's props (demo.tsx): { viewer, workspace, dataLoading, period, kpi, monthly, expenseByAccount, invoices, insightLoading, insight }. invoices is deliberately the unfiltered list, the same shape listInvoices() returns; the demo's Dashboard component keeps only sent/overdue itself (AccountingDashboard.tsx line 65, Data model above), so the same client-side filter the source runs is real code in the demo, not flattened away into a prop the recipe would otherwise be claiming for free.

Browser storage: nothing of its own, relies on S2's accessToken/refreshToken and currentWorkspaceId in localStorage; voila_lang (i18n/accounting.ts line 493 to 498) is a second, page-suite-wide key this page's own t() calls read but never write (no language switch control exists anywhere in this file).

API surface

Contracts consumed, two reads on mount plus one independent read:

Error handling is unlike billing-credits/ui/subscription-manager's: this page never reads err.response?.data?.detail or .error at all. Every one of the three calls above is individually .catch()-guarded to a safe default (null, [], the fixed sentence), so a genuinely failed read and a genuinely empty workspace render identically, an Invariant below, not merely a Gotcha. No WebSocket, no postMessage.

Application logic

1. AccountingDashboard mounts with dataLoading: true, insightLoading: true, dashData: null, insight: ''; one useEffect fires both fetchDashboard() and fetchInsight() at once, independently (line 83 to 86). While dataLoading && !dashData, the page returns <Navigation><div class="h-64"><spinner/></div></Navigation>, so only the whole content area is a spinner, nothing else renders yet, not even the header (line 96 to 104).
2. fetchDashboard runs dashboardData() and listInvoices() in parallel (Promise.all, line 59 to 62), each individually caught; it stores the dashboard body as dashData and the invoices filtered to sent/overdue as openInvoices; dataLoading goes false either way (line 56 to 70).
3. fetchInsight runs independently of step 2 and on its own timer; it can resolve before, after, or (typically) after the dashboard read, since the dashboard-data query does more work server-side. While it is in flight, the Finanzanalyse card shows five pulsing bars instead of text, regardless of whether the rest of the page has already painted (insight-generating state); insightLoading goes false either way, the fixed failure sentence standing in for a genuine error the same way the three reads above do (line 72 to 81).
4. monthly and period are derived, not stored twice: monthly maps dashData.monthly through formatMonth at render time (line 89 to 92); a null period (no fiscal year yet) suppresses the header's second line and, because the same backend early return also yields empty monthly/expense_by_account and a zeroed kpi, drives every "no data yet" branch on the page at once (empty-workspace state, Data model, accounting_router.py line 71 to 81).
5. The "Neue Analyse" button re-runs fetchInsight() only; it does not touch dashData or openInvoices (line 128 to 135).
6. Each of the four quick actions, the pending-review alert and each invoice row calls navigate(path) on click (line 160 to 168, 200 to 210, 282 to 285); none of them mutate anything, they only change route.
7. The pending-review alert renders only when kpi.pending_review > 0, with singular/plural copy ("Beleg" vs "Belege", line 206 to 208); pending_review is a count of AccountingExpense rows with needs_review = true and status = pending, a model this page's own six backend_modules do not include (Data model, Gotchas), so this one KPI is sourced from a domain adjacent to, not covered by, this wave.

Invariants

• A failed read and an empty workspace look the same: all three reads (dashboardData, listInvoices, aiInsight) are individually caught to a safe default with no error ever surfaced to the screen, so there is no way for a tenant, or for this recipe's own states, to tell "the reports read is down" from "this workspace genuinely has no fiscal year yet" (empty-workspace covers both).
• The balance shown is the balance summed server-side: revenue, expenses and profit are never computed in this component; they arrive pre-summed in kpi from the same aggregation query that produces monthly (accounting_router.py line 296 to 306), so the KPI cards and the bar chart cannot drift from each other on this page, only from whatever the backend computed.
• The insight card's own failure mode is a sentence, never a blank: fetchInsight's catch sets insight to a fixed fallback string rather than leaving it empty, so the card always shows either the shimmer, a real analysis, or that one sentence, never nothing (line 77 to 79).
• pending_review and the open-invoices list are independent signals that happen to render on the same screen: one counts receipts needing review (a domain outside this wave's six recipes), the other lists unpaid invoices (customer-invoicing-and-qr-bill-pdf); nothing on this page implies a causal link between the two, even though both read as "something needs attention".

Frontend

The rendering is the live rebuild bookkeeping-financial-dashboard/demo.tsx, built from @prima-modules/alchemy-ui, @prima-modules/tokens and plain inline SVG, rendered by the docs host as one frame per state. The page's three reads are props (dataLoading, period, kpi, monthly, expenseByAccount, invoices, insightLoading, insight); the tree is the frontmatter's. The console is rendered inside the shell rebuild (ui-design-system/ui/appshell-navigation/demo.tsx, imported relatively the way billing-credits/ui/subscription-manager's demo imports it) with an admin viewer, since the "Money" domain is adminOnly in the navigation model, on /accounting, so "Money" is the active rail entry.

States (rendering.states, in order): loading (the single spinner, the shell already painted, nothing else); default (a fiscal year with six months of activity, all four KPIs, both charts populated, six open invoices of which one is past the list's own slice(0, 5) cap, Finanzanalyse already generated); insight-generating (identical data to default, but the Finanzanalyse card still shimmering, the genuine, independent race between the two reads named in Application logic step 3); pending-review-alert (identical to default with pending_review: 3, the amber alert row between the KPIs and the charts, plural copy); empty-workspace (no fiscal year yet: the header's second line gone, both chart placeholders, "Keine Daten" in the invoices card, and the AI insight route's own onboarding sentence rather than a generated analysis, since that route hits the identical _get_current_fiscal_year early return, accounting_router.py line 231 to 232). A genuine gap this recipe does not invent a sixth state for: the Tooltip recharts shows on hover over either chart, not reproduced at all (Frontend, below), since a static server-rendered frame has no hover to show it on.

Tokens and classes as the source uses them: white cards (bg-white border-line) throughout, not the Card glass/default variants billing-credits/ui/subscription-manager's demo uses, because this file imports no alchemy-ui atom (Stack assumptions); the Finanzanalyse card's from-purple-50 via-white to-white gradient and its border-[#6844C4]/20 border are an arbitrary hex value rather than the purple token that already exists in the same tokens layer ('purple': '#6844C4', Gotchas); the bar chart's grid (#1E293B dashed) and axis ticks (#94A3B8) and both charts' (unrendered) tooltip background (#0F172A) are dark-theme slate tones with no dark mode anywhere in Labs to justify them, the same kind of stray palette billing-credits/ui/subscription-manager's Gotchas names for its own amber cards, here inside chart code instead of a card.

Responsive: grid-cols-2 lg:grid-cols-4 for the quick actions, grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 for the KPI cards, grid-cols-1 lg:grid-cols-3 for the charts row (the bar chart at lg:col-span-2); below lg everything stacks to one column. Empty state: empty-workspace, covering the header, both charts and the invoices list at once (Application logic step 4). Error state: none as such, per the Invariants above, a failed read renders exactly like empty-workspace. Loading state: loading for the very first mount only; the "Neue Analyse" click has its own scoped insight-generating look and no equivalent exists for a dashData refetch, because nothing on this page ever re-triggers one after mount.

What the demo deliberately does not render: recharts' hover Tooltip on either chart (Stack assumptions, Frontend); the donut's inline ${name} ${percent}% leader-line labels, moved to a legend list below the ring (demo header comment); useNavigate, so every quick action, the pending-review alert and each invoice row are inert, the same convention billing-credits/ui/subscription-manager's demo established for page-local navigation with no router destination inside a demo frame; the language switch t()/setLanguage() machinery, since the kit ships one committed language per copy_language. All are documented in the demo's own header comment.

Security & tenancy

What the browser may hold: S2's tokens and currentWorkspaceId only, never a payment credential; the fetched dashboard (revenue, expenses, profit, the expense breakdown, up to five open invoices' recipient names and amounts) stays in memory, not persisted. import.meta.env.VITE_API_URL is the only baked value. Origin and CSRF: the api singleton sends the Bearer header and, unlike billing-credits/ui/subscription-manager's user-only routes, an X-Workspace-ID header the backend re-validates against the requesting user's access (_get_workspace_id, api/dependencies.py line 680 to 705). Surface gating: all nine accounting routers are mounted under LABS_SURFACES (app_fastapi.py line 915 to 923), the same gate B16's admin routes and billing-credits/ui/subscription-manager's three routes sit behind.

Tenancy here is per-workspace, WorkspaceID on every one of this page's three routes (unlike billing-credits/ui/subscription-manager's per-user routes), so switching workspaces in the shell does change this page, correctly. What is hidden by CSS versus enforced: the "Money" domain is adminOnly in the navigation model (nav.tsx line 214), which hides the rail entry from a non-admin workspace member, but neither PrivateRoute (auth and surface only, PrivateRoute.tsx line 34 to 60) nor the backend's WorkspaceID/ActiveUser dependencies check a role; a non-admin member who already knows the URL, or who is a member of the workspace through a share rather than an owner invite, loads this dashboard exactly as an admin would. Not itself a defect specific to this page (every route behind these two dependencies works the same way), but worth a line here because the navigation model's own adminOnly flag reads, at a glance, like the actual boundary. Attacker-controlled input the page sends: none, this page issues no writes at all, only three reads. What the page renders from the server unescaped: the AI insight text, via a plain whitespace-pre-line div, no dangerouslySetInnerHTML; React escapes it like every other string, the markdown asterisks the prompt asks for simply show up literally rather than becoming HTML (Application logic, Gotchas).

Tests

• Colocated with the demo: bookkeeping-financial-dashboard/demo.test.tsx (vitest, jsdom, @testing-library/react), afterEach(cleanup) per _shared/test-layout: loading renders a spinner and nothing else (no header text "Voila" in the tree); default and insight-generating render the same KPI values but only one of them renders the five shimmer bars; pending-review-alert renders the alert row with "3 Belege" (plural); empty-workspace renders no fiscal-year line, "Noch keine Buchungsdaten vorhanden", "Noch keine Aufwanddaten" and "Keine Daten" all at once; the open-invoices list never renders more than 5 rows even when default's 6 open invoices are all passed; every invoice's StatusBadge in default renders the literal entries.status.<value> string, not a German word (the reproduced bug, Gotchas), proving the demo did not quietly fix it.
• The kit's render smoke: node tooling/verify/render-smoke.mjs bookkeeping/ui/bookkeeping-financial-dashboard renders all five states with renderToString and fetch stubbed; run and passing at 62ba4fc, 2026-09-12 (Acceptance checks).
• Labs at 62ba4fc has no unit test of AccountingDashboard.tsx (grep -rl AccountingDashboard frontend/src --include='*.test.*' is empty) and no Playwright spec for /accounting. Backend coverage of dashboard-data, invoices and ai-insight belongs to the backend_modules recipes' own suites, not to this page.
• What a new app adds: a jsdom test that StatusBadge's label lookup is fixed to actually fall through to invoices.status.* (a real bug this recipe's Gotchas names but does not silently correct in the demo); a Playwright spec that seeds a workspace with no fiscal year and asserts every "no data yet" sentence appears together, the gap this recipe's own error-handling Invariant documents.

Deploy & ops

Build target: the Labs Vite bundle (S2), a lazy chunk (App.tsx line 83, lazy(() => import('./pages/accounting/AccountingDashboard'))). Env baked at build: VITE_API_URL, S2's own. CSP and CORS: nothing of its own; all nine accounting routers answer on the API origin under the SPA's existing allowance, gated by LABS_SURFACES as above. Deploy path: S13's frontend rsync with the bundle; rollback is the bundle's. Nothing to migrate here directly; the schema dashboard-data reads (journal_entries, journal_entry_lines, accounting_accounts, accounting_invoices, accounting_expenses, accounting_fiscal_years) belongs to the six backend_modules recipes. Argus: a synthetic workspace session calling GET /api/accounting/dashboard-data returning 200 with a kpi object is this page's liveness; the page has no health signal of its own beyond the "no data yet" placeholders every chart and list already carries.

Gotchas

• 2026-09-12 (measured at 62ba4fc): StatusBadge (components/accounting/shared.tsx line 27 to 34) resolves its label with t(entries.status.X) || t(invoices.status.X) || t(expenses.status.X) || status, but t() never returns an empty string, a missing key falls back to the key itself (i18n/accounting.ts line 508 to 510), which is truthy. So the first call in the chain always wins, and since entries.status only defines draft/posted/void, every invoice status this dashboard actually shows (sent, overdue) renders as the literal untranslated key ("entries.status.sent") instead of the German word. Reproduced in the demo, not fixed. Fix: check for a genuinely missing translation (compare against the key) before falling through, or reorder the chain to try the caller's own namespace first.
• 2026-09-12 (measured at 62ba4fc): the AI insight prompt (accounting_router.py line 215 to 227) asks Prima for **Lage**-style markdown headings, but the page renders insight into a plain whitespace-pre-line div with no markdown parser (line 146 to 148); the asterisks reach the screen literally. Reproduced in the demo's sample text, not corrected.
• 2026-09-12 (measured at 62ba4fc): Send (a lucide icon, imported line 13) and PageHeader (imported line 17 from components/accounting/shared) are both imported and never used anywhere in the file, two dead imports, the same class of harmless leftover billing-credits/ui/subscription-manager's Gotchas names for its own CardContent and useNavigate reference (that page's own useNavigate, line 49, is also declared and genuinely called here, unlike there).
• 2026-09-12 (measured at 62ba4fc): kpi.pending_review is sourced from AccountingExpense.needs_review (accounting_router.py line 302 to 313), the receipts/Belege domain; none of this wave's six backend_modules cover expense capture or review, so this one KPI, and the alert row it drives, render real data this recipe's own backend list does not account for. Named in Purpose and Application logic rather than left implicit.
• 2026-09-12 (measured at 62ba4fc): the dashboard-data route this page's charts and KPIs actually call lives in accounting_router.py (the core journal-entries/chart-of-accounts router) alongside _get_current_fiscal_year, not inside accounting_reports_router.py; financial-reports-and-ledger is the closest of this wave's six recipes in subject matter and is named in backend_modules on that basis, but a reader expecting the dashboard's aggregation query to live inside that recipe's own file will not find it there.
• 2026-09-12 (measured at 62ba4fc): the Finanzanalyse card's gradient border (border-[#6844C4]/20, line 122) and the loading spinner's border (border-[#6844C4], line 100) both use the raw hex value rather than the purple token already defined in the same Tailwind config ('purple': '#6844C4'), a small instance of the same non-token-color habit billing-credits/ui/subscription-manager's Gotchas flags for its own amber cards.
• 2026-09-12 (measured at 62ba4fc): the bar chart's CartesianGrid (#1E293B) and axis ticks (#94A3B8), and both charts' Tooltip background (#0F172A), are dark-theme slate values with no dark mode toggle anywhere in Labs to justify them, sitting inside otherwise-light white cards; the same "stray dark palette" pattern as the arbitrary purple hex above, here specifically in the recharts config.

Reference implementation

Branch: alchemy_labs main at 62ba4fc41009b454e1c033e5036c7e8577db2061 (2026-09-12). Paths relative to the repo root:

• frontend/src/pages/accounting/AccountingDashboard.tsx (306 lines): imports and DashboardData (1 to 35), formatMonth (37 to 46), the component and its state (48 to 54), fetchDashboard (56 to 70), fetchInsight (72 to 81), the mount effect (83 to 86), derived values (88 to 94), the loading return (96 to 104), the header (106 to 119), the Finanzanalyse card (121 to 150), the quick actions grid (152 to 170), the KPI cards (172 to 197), the pending-review alert (199 to 211), the charts row (213 to 272), the open-invoices list (274 to 302).
• frontend/src/components/accounting/shared.tsx: StatusBadge (27 to 34), MoneyDisplay (40 to 51), KpiCard (145 to 172), PageHeader (178 to 185, imported by the dashboard and never called).
• frontend/src/i18n/accounting.ts: the de dictionary's dashboard.*/invoices.*/common.* keys, t() (508 to 510), formatMoney (514 to 520).
• frontend/src/services/accountingApi.ts: dashboardData, aiInsight, listInvoices and the Invoice/DashboardData-shaped types this page consumes.
• frontend/src/components/Navigation.tsx: the delegator to AppShell.
• frontend/src/components/PrivateRoute.tsx: the auth and surface gate (34 to 60), no role check.
• frontend/src/App.tsx: the lazy import (83), the route (529).
• backend/api/routers/accounting_router.py: _get_current_fiscal_year (44 to 61), dashboard_data (67 to 206), ai_insight and its prompt (208 to 227 onward).
• backend/api/dependencies.py: _get_workspace_id / WorkspaceID (680 to 779).
• backend/app_fastapi.py line 915 to 923: the nine accounting routers' LABS_SURFACES mounts.
• The demo: modules/bookkeeping/ui/bookkeeping-financial-dashboard/demo.tsx; the shell it renders in: modules/ui-design-system/ui/appshell-navigation/demo.tsx and nav.tsx.

Deviations of the reference from this recipe, all dated 2026-09-12: the StatusBadge label bug; the unrendered markdown asterisks in the insight text; the two dead imports; pending_review's dependency on a domain outside this wave's six recipes; the dashboard-data route sitting in the core router rather than the reports router; the untokenized purple hex; the dark-theme chart palette on a light page; the missing role check behind an adminOnly nav entry.

Acceptance checks

From alchemy_labs/frontend at 62ba4fc with the harness up (tooling/verify/labs-local.sh up, a workspace-owner session), or from a new app built to this recipe:

1. grep -n "\.catch(() =>" src/pages/accounting/AccountingDashboard.tsx prints 2 lines (the dashboard and the invoices read, line 60 to 61); grep -c "err.response" src/pages/accounting/AccountingDashboard.tsx prints 0, unlike billing-credits/ui/subscription-manager's 3, confirming this page never inspects the envelope at all (API surface).
2. grep -n "t(\entries.status" src/components/accounting/shared.tsxprints theStatusBadgeline; a browser walk-through against a seeded workspace with asent` invoice shows the badge reading the literal key, not "Versendet" (Gotchas).
3. Browser walk-through, signed in as a workspace member with a fiscal year and at least one sent/overdue invoice: (a) open /accounting, observe the shell paint first and a bare spinner where the whole content area will be, then the full page at once (no partial paint); (b) observe the Finanzanalyse card shimmer independently, sometimes finishing before the rest of the page has fully painted and sometimes after; (c) with more than 5 open invoices seeded, count the rows in "Offene Rechnungen": exactly 5; (d) as a non-admin member of the same workspace who cannot see "Money" in the rail, paste the /accounting URL directly, observe the dashboard loads anyway (Security and tenancy).
4. Demo gate: node tooling/verify/render-smoke.mjs bookkeeping/ui/bookkeeping-financial-dashboard renders all five states, 0 failures, 2026-09-12. npm run check passes on this recipe's frontmatter shape, heading order, the internal-term scan and the states list matching the demo's exported keys.
5. Verifier: node tooling/verify/compare.mjs bookkeeping/ui/bookkeeping-financial-dashboard --state default --docs http://127.0.0.1:4321 --app http://127.0.0.1:3020 --session-file tooling/verify/.labs-local/session.json (a workspace-owner session with a fiscal year and open invoices seeded) writes a report with page_errors: []; mismatch_ratio is read for the header, the KPI row and the Finanzanalyse card only, since the app's monthly totals, expense breakdown and invoice rows are the harness's seeded account and the demo's are sample data.