The web app

Stabiso ships a web client for people who work in the books every day. It is built with Microsoft's Fluent UI, restyled to a calm design of its own (Design), and is laid out the way people who come from modern SAP and Oracle ERPs expect:

• a sidebar that is always in view, grouped by business area (General ledger, Sales, Purchasing …);
• one context control on every page: the company, its currency and whether the period is open;
• a Home page that is a ranked work queue ("Needs attention");
• list pages that open card pages, with FastTabs;
• a worksheet-style General Journal;
• "Tell me" search on Alt+Q: pages, actions and records (an invoice number, a customer).

The UI is a client of the same REST API that agents and integrations use, with the same approval policy, four-eyes rule and audit trail. The API server serves it at /app.

Screens

A credit note opened from an invoice waits for its current remaining allowance and account details before its lines can be edited. Receipts and payments opened from an invoice refresh its open balance before suggesting the amount. After a partial payment, the next receipt starts with what is still owed. Bulk submission stays busy until the refreshed list is ready; a draft changed by someone else can then be selected again with its current version.

Trial Balance	Approvals	Tell me (Alt+Q)

Setup has screens for the company profile and for customers and vendors (addresses and the rest of their cards); entities, fiscal years and their calendars (4-4-5, thirteen periods, adjustment periods; see Fiscal calendars) and tax books are created through the API. The report pages pick dates; reports by fiscal period, with year to date and comparatives, are in the API (reports/period-profit-and-loss).

Tell me

Alt+Q (or the search box in the header, "Search or tell me what to do") opens Tell me. With nothing typed it lists, as groups with headers a screen reader announces: Recent (the last five entries you opened through Tell me or the navigation, kept per user in this browser and cleared at sign-out; the page the app opened on does not count), then Actions (New Journal Entry, New Sales Invoice, Record Receipt, Upload Bills, Import Data, ...), Finance, Sales, Purchasing, Banking, Reports (with Analytics) and Settings; a section header is in small capitals with a rule above it. A section you may not use is left out; inside a section the entries are in alphabetical order of your language. With a query it is one list ranked by how well the entry matches: exact, then the start of the title, the start of a word, inside the text, and, only when nothing matches in those ways and the word has four letters or more, the letters in order ("tbal" finds Trial Balance); the matched letters are in bold. Each entry also answers to synonyms in English, German, French and Italian whatever the interface language: "Debitoren" or "AR" finds Customer Invoices, "Buchung" the General Journal, "MWST" or "VAT" VAT Returns, "Kurs" or "FX" Exchange Rates. Equal matches are ordered by recent use, then alphabetically. The catalogue is ui/src/lib/commands.ts; a unit test reads the routes of App.tsx and fails when a page has no entry, so a new page must be added there (with its area and its synonyms in the four catalogues, tellMe.keywords.<id>).

With a query of two characters or more it also searches the organization's records (GET /v1/search, the read permission): sales invoices and credit notes, vendor bills and credit notes, purchase orders, journal entries, payments, customers and vendors, in every company of the organization (in a test copy, that copy's). Numbers and references are compared on their letters and digits only, so inv2026000012, INV-2026-000012 and 2026-000012 find the same invoice; a vendor's own invoice number, a payment or QR reference, an order or buyer reference, a journal entry's source, a VAT number, a name or an entry's description find it too. The records come below the pages and actions (so the entry under the keyboard does not move when they arrive), under a header per type, best match first: the exact number, then a number that starts with the text, then the rest, newest first, at most five of a type. Each shows its number and customer or vendor, the company, date, amount and status, and, when the text was found elsewhere than in the number or name, where ("Vendor's invoice no.: BM-4411"). Opening a record of another company switches to that company; a payment opens its journal entry. Agents use the same search as the MCP tool find_records.

Filling in a form

Every field says under it what goes in it, with an example. Where the usual values are known, they sit under the field as chips: one click fills them in (the service-level standards of a support queue, an inbox address of your company's domain). A code is made from the name as you type it, and a new record starts with the settings most companies keep. Forms whose answers depend on your business have Suggest with AI: it proposes a value for each field it can, each with a sentence saying why, from what the form is for and your company's country, industry and currency. It never saves anything and never makes up names, addresses, amounts or bank details; check what it put in and save. When the AI does not answer within about half a minute, the form stays as it was and the button asks you to try again (ADR-0112).

Suggest with AI is on the support queue form, on New account of the chart of accounts (the type and the report line an account of that name belongs to) and on a new field of your own under Settings › Your own fields (whether it takes text, a number, a date, yes or no or a choice, and the choices). A country, such as a new customer's or vendor's, is picked from the list of countries, your company's own first. The code of a cost centre or project, of one of its values and of a price list is made from the name when you leave it empty (Wholesale CHF is WHOLESALE-CHF), with -2 added when the code is taken; the API does the same when the code is left out. Filters above a list and the choices of a report carry no hint: what they narrow is their label.

Keyboard

Number fields (a quantity, a price, an amount, a rate, a number of days) choose their whole value when you enter them by click, Tab or touch, so what you type replaces it: a quantity that starts at 1 becomes 10 when you type 10. A second click places the cursor inside the number as usual.

An address the app has no page for (mistyped, or an old link) shows "Page not found" with the address and a link to Home; it never jumps to Home on its own.

Design

One set of tokens, ui/src/app/theme.ts, styles every screen. The Fluent theme is built from it (so every Fluent component, from a button to a dialog, takes its colours), and the shared components (PageHeader, Panel, Cue, Kpi, StatusBadge, DataTable, FastTabs) take the rest from its ui object. A page does not write a colour, a shadow or a font of its own: it uses these components, Fluent's tokens, or ui. A new screen picks up the design by being built from them.

• Type: Geist, self-hosted (@fontsource-variable/geist, the CSP allows no font host), 14/20 px. Every figure is tabular (tabular-nums). Page titles are 28 px, card titles 15 px.
• Shape: radius 4 (keycaps, chips), 6 (buttons, fields, navigation items), 8 (cards). No shadows in the page; only what floats (menus, dialogs, tooltips) has one. Hover changes the background only (120 ms), never lifts.
• Page head (PageHeader): the breadcrumb (the business area, and on a record the list it belongs to as a link; up names the list of a page whose address does not, such as a document under Customer invoices or Vendor bills), the title, what the page is for, and the actions on the right. Every page but a list has a Back arrow before the breadcrumb (on a phone, the arrow and the page's name): it returns to the page the record was opened from (its name is the arrow's label, "Back to C-HH Hamburg Handel GmbH"), or to its list when it was opened by its address.
• Going back (app/history.ts): a list comes back with the filters and view in its address and its scroll position, whether by the Back arrow, the breadcrumb's link or the browser's Back; a column sort is not kept. The breadcrumb's link remembers each list per company, so a filter set in one company never follows into another. A page opened anew starts at its top. Cancel on a form goes back the same way. Saving an edit returns to the record's card (back in the history when the form was opened from it, so the form is not left behind), and saving a new record replaces the form with the card, so Back never reopens a form.
• Fields (Fields, in a FastTab): the label left, the value right; a value too long for the space beside its label moves under it and wraps at its punctuation (an email after the @), never past the card's edge. A field without a value shows a dash.
• Cards (Panel): white, hairline border, a 15 px title with optional meta on the right (meta), and flush for a list that runs to the card's edges.
• Lists: status views as tabs, each with its count (ListViews), above the filters; rows picked with their boxes (DataTable's selection) swap the filters for a teal bar of bulk actions (BulkBar, selected rows #f2f7f6). A date past due carries "N days overdue" in rust under it.
• Status (StatusBadge): a chip with a dot. Green is done (posted, paid), blue is open, amber waits on someone (pending approval, partially paid), grey is a draft or inactive, rust is a problem (rejected, variance).
• Focus: a 2 px teal ring, 2 px off the element, on everything you can click.

The operator portal (/admin) shares the tokens and components but keeps its own red header, so an operator cannot mistake where they are.

On a phone or a tablet

The same app, three layouts (the breakpoints are in ui/src/lib/responsive.ts and ui/src/styles.css):

Lists on a phone. A list of records (invoices, bills, journal entries, open items, approvals, accounts, orders, payments …) has no table on a phone: each row is a card with the record's number or name and its amount on the first line, the party or description under it, and the dates, status and other fields as small captions with their values; buttons of the row sit at its foot. A tap anywhere on the card opens the record, as a click on a row does on a desktop; for the keyboard and screen readers the card's title is a button named by the record's number or name, the card's one tab stop (its own buttons follow it). The cards show the same rows as the table (a browser test compares them with the API). Sorting by a column heading is a desktop and tablet feature. Tables inside a record (the lines of a document, a depreciation schedule, the VAT breakdown) are wider than a phone, so they scroll sideways inside their panel (on a tablet with their first column held in place).

The screenshot sweep keeps every route at 375 x 812 and 768 x 1024 as well as at 1280 and 1600 (CI artifact ui-screenshots, files 375-*.png, 768-*.png, plus 375-menu-open.png and 375-tell-me.png), and fails when the page is wider than the screen or a control a finger must hit is smaller than 44 px.

Languages

The UI speaks English, German, French and Italian, in their Swiss variants: en, de-CH (Swiss High German: "ss", never "ß"), fr-CH and it-CH.

• The UI starts in the browser's language (any German, French or Italian browser setting maps to the Swiss variant). Other languages get English.
• Users can pick a language under their avatar → Language. The choice is saved on their user (PATCH /v1/me with {"locale": "de-CH"}, null to follow the browser again), so it follows them to every browser. GET /v1/me returns it as locale.
• <html lang>, numbers and dates follow the language. German, French and Italian use Swiss formats (1’234.50, 01.09.2026); English uses the browser's English variant (en-US, en-GB…) or Swiss formats otherwise. Date pickers are drawn by the browser in its own language.
• Amounts show as many decimals as their currency has under ISO 4217: JPY 0, CHF and EUR 2, KWD and BHD 3. Formatting works on the decimal string from the API, never on floats.
• Messages from the server (for example a policy's reason or a validation error) are shown as the server wrote them, in English. Account names, descriptions and other data are shown as entered.

Adding a string or a language

Translations live in ui/src/i18n/locales, one JSON catalog per language, grouped by screen (journal.*, entry.* …) plus shared groups (common.*, column.*, page.*).

• A new string: add it to en.json, then to de-CH.json, fr-CH.json and it-CH.json, and use it with const { t } = useTranslation(); t("area.key"). Keys are type-checked against en.json, so a typo fails npm run typecheck. npm test fails when a catalog lacks a key, drops a {{placeholder}}, misses a plural form its language needs (_one, _other, plus _many in French and Italian) or contains "ß".
• Codes from the API (statuses, sources, account types, report lines) are labelled by the helpers in ui/src/i18n/labels.ts. An unknown code falls back to a readable form of itself.
• A new language: add its catalog, register it in LOCALES, LOCALE_NAMES and resources in ui/src/i18n/index.ts, and add the tag to Locale in src/erp/modules/users.py so users can save it. The database accepts any well-formed tag.

Terminology

Use these terms so screens, reports and documentation agree:

Report lines follow the Swiss Code of Obligations (art. 959a/959b), e.g. "Nettoerlöse aus Lieferungen und Leistungen", "Flüssige Mittel", "Aktive Rechnungsabgrenzungen".

Users, roles and sign-in

People sign in with their Google account, or, without one, with their email address and a password that Google Identity Platform keeps (ADR-0037). Either way Google is the identity provider and the ERP stores no password, and every sign-in then ends with the person's passkey (Passkeys). An administrator invites an email address and picks a role; for someone without a Google account they tick E-mail a link to set a password (or choose it later in the user's menu), and Google sends the person that link:

Each person acts as themselves (user:<id> in the audit trail). The policy rules apply exactly as they do for API keys:

• nobody approves their own request;
• periods are closed only by a person with approve;
• an Accountant without post scope sees their entries go to the Approvals list.

These are the rights the invitation gives. Settings → Roles then gives a person a ready-made or an own role, which also sets the areas of the app they open and which sales records they see, shows the app as they see it and suggests taking away rights nobody used for 90 days (Roles).

An email can belong to several organizations. At sign-in the UI then asks which organization to open.

How sign-in works

1. The browser gets a Google ID token from Google Identity Services.
2. POST /v1/auth/google verifies the token's signature, audience (ERP_GOOGLE_CLIENT_ID) and expiry, and requires a verified email. When ERP_ALLOWED_EMAIL_DOMAINS is set, both the email domain and the Google Workspace domain (the hd claim) must be on the list. A personal Google account registered with a company address therefore cannot sign in. A user is tied to the Google account that first signs in (sub). Another account that later verifies the same address is refused.
3. The answer asks for the person's passkey (status: passkey): the browser has them touch it, or create the first, and POST /v1/auth/passkey checks the answer (Passkeys). Only then does the server set an HttpOnly, Secure, SameSite=Strict session cookie. Only a SHA-256 hash of the session is stored (user_session), with the time of the last passkey touch; a session without one opens nothing. Sessions last 12 hours (ERP_SESSION_HOURS).
4. Every state-changing request from the browser carries X-ERP-UI: 1, and the API refuses cookie-authenticated writes without it. Together with SameSite this blocks cross-site request forgery.
5. Disabling a user revokes their open sessions immediately.

With a password, step 1 and 2 differ: the browser sends the address and password to Google Identity Platform (accounts:signInWithPassword), never to the ERP, and POST /v1/auth/password verifies the ID token Google returns (signature, the project as audience and issuer, expiry, a verified address, the password provider). It counts only for the user whose account the ERP set up (Identity Platform's id is kept as password_subject when the password e-mail is sent). The domain list works the other way round: people of those Workspace domains, and anyone who has signed in with Google, get no password, so their Workspace keeps deciding whether they may sign in; every other invited address may use one. Google refuses repeated wrong passwords; the ERP also limits refused sign-ins per client address. Forgot password? on the sign-in page has Google e-mail a link to set a new one.

The UI's Content Security Policy allows scripts only from the ERP itself and from Google Identity Services, connections to Google Identity Platform for password sign-in, workers and the web app manifest only from the ERP itself, and forbids framing.

Setting up Google sign-in (once per project)

1. In the Google Cloud console, configure the OAuth consent screen. Choose Internal if your users are in your Google Workspace organization.
2. Create Credentials → OAuth client ID → Web application and add the erp-api URL (e.g. https://erp-api-…run.app) as an Authorized JavaScript origin.
3. Re-run ERP_GOOGLE_CLIENT_ID=<client id> ./infra/bootstrap.sh <project>. Add ERP_ALLOWED_EMAIL_DOMAINS=example.ch to restrict sign-in to your domain.

bootstrap.sh invites the Cloud Shell account as an administrator of the demo organization. For another organization, ./infra/erp-create-org.sh "Name AG" creates it. You then invite people under Settings → Users, or with POST /v1/users using the organization's admin key.

Install it as an app

Stabiso is a progressive web app: it can be installed and then opens in a window of its own, with its own icon, like any other application. It still works online only (see ADR-0021).

Installing is optional and changes nothing in the ERP: people sign in with Google as before, and the same roles and approvals apply. To remove the app, uninstall it as any other app (desktop: the app window's menu, Uninstall; phone: press and hold the icon).

What the app caches. Only the program files of the UI: the built scripts, styles and icons and the page shell, so the app opens quickly and can show that it is offline. Never data: nothing the API returns (balances, entries, documents, reports), no PDFs or other downloads, nothing about sign-in. Financial data is always fetched when you look at it.

Offline. When the connection is lost, a banner says "You are offline". What is on screen stays as it was loaded and may be out of date; posting, approving and every other change is refused with the message that nothing was sent (nothing is saved on the device and nothing is sent later). A page opened while offline says that it needs a connection. The banner goes and the data refreshes when the connection returns.

Updates. A new release is picked up the next time a page is loaded. A window that stays open shows A new version is available with Reload and Later; the page reloads only when you press Reload (if you typed on the page it asks you to press once more, because reloading discards the input). With the app open in several windows, Reload in one window does not reload the others; each shows the prompt until you press Reload there, which then reloads it at once.

For developers. npm run build writes dist/sw.js (the worker, with the list of files to cache inserted by ui/pwa-plugin.ts) next to manifest.webmanifest and the icons; npm run dev registers no worker. The rules for what a worker may handle are one file, ui/src/pwa/rules.ts, tested against every route of the generated API client. The icons are drawn by tools/pwa_icons.py; run it only to change them.

Local development

# a seeded server (throwaway Postgres, demo data, dev sign-in) serving ui/dist
cd ui && npm ci && npm run build
cd .. && uv run python -m tests.erp.e2e_server --port 8765
# open http://127.0.0.1:8765/app/ and sign in as alice@example.com (admin),
# bob@example.com (controller), carl@example.com (accountant) or vera@example.com (viewer);
# erin@example.com (admin), finn@example.com (controller) and gina@example.com (accountant) work in
# Muster Handel AG, a real organization with the same books, which can have test copies

# or hot reload: Vite proxies /v1 to the API
ERP_API_URL=http://127.0.0.1:8765 npm run dev     # http://127.0.0.1:5173/app/

Development sign-in (ERP_DEV_LOGIN=1) takes just an invited email. It is refused whenever ERP_ENV=cloud, which the container image sets by default. The same server serves the operator portal at http://127.0.0.1:8765/admin/ (sign in as operator@example.com); see the portal.

Charts

The charts are plain SVG in ui/src/components/charts (ADR-0030); there is no charting library. To add one:

1. Put the numbers in a ChartModel (components/charts/model.ts): categories, series with the API's decimal strings, format (the app's amount format), and drill(series, category) returning the route a mark opens. The builders for the Analytics screen are in lib/analytics.ts, with their tests.
2. Draw it with BarChart, LineChart, Sparkline or HBarChart inside a ChartFrame, which adds the title, the legend (from two series) and the Show as table toggle. A chart without a table, a link on every mark and a drill-down that shows the same amount does not meet the UI rules.
3. Use the series colours in order (seriesColor(i): --viz-1 .. --viz-8, defined in styles.css); ordered buckets take the one-hue ramp (bucketColor). A series keeps its colour whichever others are shown.
4. The server computes every number; the browser formats and draws. Never print a float of an amount.

Code layout (ui/src)

api/client.ts, schema.d.ts   typed client (openapi-fetch); CSRF header, Idempotency-Key, errors
app/                         App routes, Shell (header, context button, Tell me), Sidebar and NavDrawer,
                             navigation.ts (the one navigation model), company context, theme.ts (design tokens)
auth/                        sign-in page (Google and dev), session hook
components/charts/           the chart set (line, grouped and stacked bars, sparkline, horizontal bars)
                             in plain SVG, with the table alternative; the arithmetic is lib/charts.ts
components/                  PageHeader, Panel, Cue, Kpi, StatusBadge, DataTable (sortable, keyboard), FastTabs, TellMe,
                             bill upload (several files, a few at a time), attachments, send and mark as sent
i18n/                        languages: catalogs (locales/*.json), selection, labels for API codes
pwa/                         installable app: rules for what the service worker may handle (rules.ts),
                             the worker (worker.ts, sw.ts), registration and the update prompt,
                             offline banner and write guard; the build plugin is ui/pwa-plugin.ts
lib/                         formatting (locale, currency decimals), journal balancing (exact cents),
                             document lines (exact amounts, payloads, bill file detection), command registry
pages/                       Home (RoleCenter.tsx), Analytics (pages/analytics: period bar, KPI strip, trends,
                             breakdowns, insights), accounts, journal, entries, approvals, reports, users,
                             customers and vendors (list and party card),
                             customer invoices and vendor bills (lists, document card, entry form,
                             QR-bill, bill upload), vendor payments (pain.001), payment proposal,
                             record payment/receipt, bank statements and reconciliation worksheet,
                             VAT returns (periods, return card with drill-down and finalisation),
                             period close (fiscal-year periods, close checklist, period-end runs, close and reopen),
                             exchange rates (ExchangeRates.tsx and pages/fx/: one component per tab, a dependency-free
                             SVG chart; the logic that is not a component is lib/fx.ts),
                             data import (check, import and templates for CSV and Excel files),
                             archive export (a ZIP of the stored files of a date range, for an auditor)

The operator portal (/admin)

A separate app for the platform operator (ADR-0032), served at /admin/ with its own route tree, its own sign-in (an address on ERP_PLATFORM_OPERATORS, Google, then a session cookie that only /v1/platform accepts) and a banner that says every screen is in operator mode: it acts on the platform for every customer, not inside one organization. It is English only: two people use it and its language is fixed, so it has no translation catalogs; everything else (the layout rules, the phone cards, the 44 px targets, tiles that open what they count) is the ERP's.

There is no delete and no purge in the portal: purging a demo is erp platform purge-demo (deployment).