Appearance
SPEC-018: Account home, usage recording and the owners' view
APPROVED 2026-10-15 by the Product Owner with ADR 0041 (issue #280). It narrows the not-doing line "Dashboard or chat UI of our own" to "no dashboard of the books themselves". It amends SPEC-017 S2, S6 and S19: after signing up, connecting Xero or paying, people now land on the account home (
/), not on/start.
AMENDED 2026-11-03 (issue #297, codebase review): the /admin route reads admin_overview, admin_revenue and admin_trends with the signed-in operator as the person in context (S21). In the next release (issue #349, held back one release by change protocol rule 2) each function will refuse unless the person in context is one of the two operators. That check stops a caller that has set no context. It has the same trust level as row-level security: anyone holding the app role's login can still claim to be an operator by setting the context. Fully closing that needs a separate database role, an open point beside the webhook role in ADR 0037.
AMENDED 2026-11-04 (issue #349): the refusal is now live (migration 0035). Each of the three functions first calls require_operator, which refuses with an error unless app.principal_id names a person whose email is one of the two operators. It refuses a caller with no one, or someone else, in context. It does not stop someone holding the app role's login who sets an operator's id as the context: it trusts app.principal_id, as row-level security does (ADR 0037's note).
Business intent
Rob (director) found /start confusing: it mixed sign-up, terms, Xero, the subscription and the Claude connector steps on one page. He could not tell whether he had to subscribe or where to go next, and there was no home on the web. The owners also cannot see whether anyone uses GetMy Books, which a buyer will ask.
This slice gives each signed-in person a plain account home, records which tools are used (never what was in them), and gives the two owners one page of counts. The books themselves stay in Claude: no figure from anyone's books appears on any of these pages.
User stories
- As an owner-director, when I sign in, I want one page that says, for each of my companies, whether Xero is connected, whether the profile is set and whether it is subscribed, and how to add GetMy Books to Claude, so that I know what to do next.
- As one of the two owners of Get My Books Ltd, I want one page of counts (who signed up, who connected Xero, who used it from Claude, who pays, and which tools are used) so that I can see whether the product works, without seeing anyone's books.
Scope
1. Usage recording
- Table
usage_event(migration 0021): id, principal (cascade on delete), entity (nullable, cascade on delete), time, tool name, outcome (okorerror). Indexed by (entity, time) and (principal, time). - What is recorded: after every
tools/callon the GetMy Books MCP server, the tool's name, whether it worked, who called it (the signed-in principal) and which company, when the call named one in itsentityargument and that name resolves for this person. Nothing else: no arguments, figures, file names, findings or any other books content (ADR 0036 rule 1). - Never in the way: recording happens after the result is computed and is not awaited. A database error is logged as a warning and the tool's result is returned unchanged. The setup-notice server (SPEC-017 S20) records nothing.
- Row-level security: a person may add only their own rows, for no company or a company they have access to. They may read the rows of the companies they have access to, and their own rows with no company. The app may not update or delete rows.
- Retention: 13 months.
delete_old_usage_events()(owned by the owner role, executable only by the app) deletes older rows, from the same 15-minute sweep that deletes old write previews. Deleting a company or an account deletes its usage rows (the foreign keys cascade).
2. The account home (GET / on mcp.getmy.group)
- Signed in through Cloudflare Access, as
/startis. A person with no account, or who has not accepted the current terms, is sent to/start. - It says, in one line, what works without a subscription, matching the licence gate (
LicenceGateinsrc/mcp/context.ts): Claude can check a company's books once it is subscribed; connecting Xero, setting the company profile and adding a bank account work without a subscription. - One card per company: its name; Xero connected or not (with a Connect Xero link if not); company profile set or not (with a hint to ask Claude to set it up); the subscription: Active (with the renewal date), Free (comped), Not subscribed (Subscribe at £19.99 a month, through the existing checkout form), Cancelled (with the date it ended) or Payment due; Manage billing (the existing
/billing/portal) where a Stripe customer exists; and this calendar month's use (Europe/London): checks run (tool calls that worked), changes approved (activity logapprovedrows) and when it was last used. - Claude: "Connected" with when it was last used, once this person has any usage row; otherwise the steps to add the connector, with the server URL
https://mcp.getmy.group/mcp. These steps move here from/start. - Add another company (the existing Xero connect), and Account: Download my data, Delete my account, the Terms of service and the Privacy notice (on getmy.group).
- Every read runs under row-level security as the signed-in person (
src/platform/account-home.ts);src/web/home.tsonly renders. - Server-rendered, no script, the UI kit's tokens; cards stack on a phone; light and dark follow the computer.
3. Where people land
/startstays for creating an account and for accepting new terms. Once a person has an account with the current terms,GET /startsends them to/.- After
POST /start, after the Xero callback connects a company, and after Stripe Checkout (done or cancelled), people are sent to/. Stripe's success and cancel addresses become/?checkout=doneand/?checkout=cancelled, which show a fixed note; the old/billing/successand/billing/cancelledaddresses redirect there. GET /signin/<provider>(ADR 0038) sends people to/.
4. The owners' view (GET /admin)
- Who: Cloudflare Access has a separate path application on
mcp.getmy.group/adminthat admits only the two operators, through the Entra login with MFA. Its tokens carry their own AUD, given to the app asCF_ACCESS_ADMIN_AUD. The app verifies the token against that AUD and checks the email against a fixed list of the two operators. - Refusals: not configured (no
CF_ACCESS_ADMIN_AUD) 503 "The owners' view is not configured."; not signed in 401; anyone else 403, with no detail. Refusals are logged without the email. - What it shows, from
public.admin_overview()(aggregates only): counts (people, companies, companies with Xero connected, companies with a profile, subscriptions by status, comped); the sign-up funnel (signed up, with a company, with Xero connected, used from Claude, paying); per tool, calls and errors in the last 30 days; and per company its name, when it was created, how many people use it, Xero connected, profile set, subscription status, comped, tool calls in the last 30 days and when it was last used. Monthly revenue is what active, non-comped subscriptions actually charge per month after their discounts (amended 2026-10-15: not a count times 1999 pence, which counted the 100%-off test subscription as £19.99). The webhook records each subscription's amount in integer pence (src/billing/monthly-amount.ts, migration 0022); cancelled, refunded and past-due ones are not active. "Paying" counts those that charge something; any recorded before amounts were stored are named in a note until Stripe next updates them. - Charts (amended 2026-10-15, the Product Owner: "graphs on this page we can swap between instead of tables of empty data"), from
public.admin_trends()(migration 0023): one chart panel with four tabs, plain links (/admin?view=activity|signups|tools|subscriptions, the current one markedaria-current="page", anything else the first): companies with a tool call per London week and people signed up per London week, each for the last 12 weeks (bars; Claude connecting is not a tool call); tool use in the last 30 days (horizontal bars, errors as a second, labelled segment); and companies by subscription status in plain words (Active, Not subscribed, Cancelled, Payment due, Free, Trial). Server-rendered SVG, no script; each chart has an accessible name, each bar its exact value on hover, and a table view. A chart or table with nothing but zeros is replaced by a one-line empty state. The funnel stays a table, with each step's share of sign-ups; its paying step counts the people with a company whose subscription is active, not comped and charges something, by the same rule as the Paying tile (a 100%-off subscription is not paying). - What it never shows: books data, Xero tokens or tenant ids, Stripe ids, or any person's email.
Out of scope
- Any figure from a company's books on the web (the not-doing line stays for that). Charts or scripts on these pages.
- Recording tool arguments, or anything said in Claude.
- Changing the licence gate, the price or the checkout flow.
- Showing a subscription that is set to cancel at the end of its period:
entity_subscriptiondoes not record Stripe'scancel_at_period_end, so the home says "renews on <date> unless cancelled".
Integration sketch
src/platform/migrations/0021-usage-event.sql: the table, its indexes,delete_old_usage_events()andadmin_overview().src/platform/policies.sql: the two policies.src/platform/bootstrap.sql: no update or delete for the app.src/platform/usage.ts: record one event, and the retention delete.src/mcp/usage.ts: the hook ontools/call, installed bycreateMcpServerwhen given a recorder (the web app and stdio give one).src/platform/account-home.ts: the home's reads.src/web/home.ts: the page.src/web/onboarding.ts: the/route and the redirects.src/platform/migrations/0023-admin-trends.sql:admin_trends(), the weekly series and paying people for the charts.src/platform/admin-overview.ts: callsadmin_overview(),admin_revenue()andadmin_trends().src/web/admin.ts: the operator list, the door and the page; its charts are the kit'sbarChart,hBarChartandchartPanel(src/web/ui/).src/main.ts: the second Access verifier whenCF_ACCESS_ADMIN_AUDis set.
Scenarios
S1: Every tool call is recorded, without its arguments
Given Rob is signed in and has access to "Acme Ltd" When Claude calls bank_reconciliation_check with entity "Acme Ltd" and a statement file Then a usage row records Rob, Acme Ltd, bank_reconciliation_check and outcome ok And nothing from the arguments is stored
S2: A failed call is recorded as an error and returned as it was
When a tool call returns an error result, or its handler throws Then a usage row records outcome error And the error result, or the thrown error, reaches Claude unchanged
S3: Recording never gets in the way
Given the database refuses the usage row When a tool call completes Then its result is returned unchanged and a warning "Could not record tool usage" is logged
S4: A company the person cannot see is not recorded against it
When a tool call names a company the person has no access to Then the usage row has no company When a tool call names no company (deadlines_upcoming, connection_check) Then it counts once for each company the person has, one or several (such a tool checks them all), or for none if they have no company yet And Claude connecting never counts for a company (Amended 2026-10-15: the Product Owner's deadlines check did not show on FEAW's card.)
S5: The setup notice records nothing
Given a person with no GetMy Books account When Claude calls a tool on the setup-notice server Then no usage row is written
S6: Usage rows are guarded by row-level security
Given Rob has access to Acme Ltd only Then Rob can add a usage row for himself with no company or for Acme Ltd, and not for another person or another company And Rob reads Acme Ltd's rows and his own rows with no company, and nobody else's And the app can neither change nor delete a usage row
S7: Usage goes with the company and the account
When Acme Ltd is deleted, or Rob deletes his account Then their usage rows are deleted with them
S8: Usage is kept for 13 months
When the sweep runs Then usage rows older than 13 months are deleted and newer ones are kept And only the app may run delete_old_usage_events
S9: The home needs an account with the current terms
When a signed-in person with no account, or who has not accepted the current terms, opens / Then they are sent to /start
S10: The home shows each company's state
Given Rob has "Paid Ltd" (Xero connected, profile set, subscription active until 12 November 2026) and "New Ltd" (no Xero connection, no profile, no subscription) When Rob opens / Then Paid Ltd shows Xero connected, profile set, Active renewing on 12 November 2026 and Manage billing And New Ltd shows Connect Xero, a hint to ask Claude to set up the profile, and a Subscribe button for £19.99 a month
S11: Every subscription state is said plainly
Then a comped company shows Free, a cancelled one shows Cancelled with the date it ended and a Subscribe button, a past-due one shows Payment due with Manage billing, and any other status shows Not subscribed
S12: The home shows this month's use
Given Paid Ltd had 3 tool calls that worked and 1 that failed this month, and 2 approved changes Then its card shows 3 checks run, 2 changes approved and when it was last used
S13: The home says what works without a subscription
Then the home says Claude can check a company's books once it is subscribed, and that connecting Xero, setting the company profile and adding a bank account work without a subscription
S14: The Claude section
Given Rob has never connected GetMy Books to Claude Then the home shows the steps to add the connector, with https://mcp.getmy.group/mcp Given Claude has connected (the MCP handshake's initialized notification, recorded as "(connected)" with no company), or he has used a tool Then it shows Connected, with when he last used it And the connection is not counted as a check on any company card, nor listed as a tool in the owners' view (Amended 2026-10-15: the Product Owner connected Claude and the home still said "Not set up", because only tool calls counted.)
S15: The account links
Then the home links Add another company, Download my data, Delete my account, the Terms of service and the Privacy notice
S16: People land on the home
When a person with an account and the current terms opens /start, posts /start, finishes connecting Xero, or comes back from Stripe Checkout, or arrives from /signin/<provider> Then they are sent to / And coming back from Checkout shows a fixed note: done (the subscription goes live once Stripe confirms it) or cancelled (nothing was charged)
S17: The owners' view admits only the two operators
When /admin is opened with no CF_ACCESS_ADMIN_AUD set, it answers 503 "The owners' view is not configured." When it is opened with no valid token for the admin AUD, it answers 401 When the token's email is not one of the two operators, it answers 403 with no detail, and the log does not name the email
S18: The owners' view shows counts only
Given an operator signed in to /admin Then they see the counts, the sign-up funnel, a chart panel with tabs for weekly active companies and weekly sign-ups (12 weeks), tool use (30 days) and subscriptions by status, the per-company list and the monthly revenue (what active, non-comped subscriptions charge) And the funnel's paying step agrees with the Paying tile And a chart or table holding only zeros is replaced by a one-line empty state And no books data, tokens, Stripe ids or emails
S19: admin_overview returns aggregates and is hardened
Then admin_overview runs as its owner with search_path pg_catalog then pg_temp, only the app may execute it, and its result holds no email, token or Stripe id
S20: Wording and accessibility
Then the home and the owners' view follow ADR 0036 (no advice, no "verified", no accountant service), pass the accessibility checks (one h1, labelled inputs, named links and buttons), use only the colour tokens, and stack on a phone
S21: The owners' view's functions check the caller (issue #297, 2026-11-03)
Given an operator signed in to /admin Then admin_overview, admin_revenue and admin_trends are read with that operator as the person in context, and answer And an email with no person behind it reads nothing But called with another person in context, with no one, or with an empty context, each refuses with an error and returns nothing (live since issue #349, migration 0035, 2026-11-04)
Exit test
The Product Owner signs in with a fresh email, creates the account on /start and lands on /, connects a Xero demo company and sees its card (Xero connected, profile not set, Not subscribed), adds the connector in Claude and runs connection_check, reloads / and sees Claude connected and one check run, then opens /admin and sees the new person in the funnel. Rob opens /admin and is admitted; a third email is refused.