Skip to content

Backstage

Backstage is Tomoda's Backstage UI and the layer the app is run from. This page is the system view: who Tomoda accounts are, how they get in, what decides what they can do, and what gets recorded. Endpoints live on Backstage service; account type policy, links and step-up on Authentication.

Information architecture

Backstage exists so the owner and ops team can run, maintain, change, fix and monitor Tomoda from a phone, without a dev computer. Every screen is judged by one question: can an operator finish this task on a phone without knowing the code? That means plain-language names, one line saying what each screen and tool is for, guided flows instead of raw inputs, clear confirmations and results, and one coherent structure.

Screen Dock What it is for Main tasks
Dashboard yes The state of Tomoda at a glance Read the key numbers as an Overview, open Traffic, Content, Safety, Support or Ops for focused charts and lists, follow a count to the screen that clears it. The header bell lists what needs a person: new reports, review requests, cases assigned to you, photo reviews and failed jobs
People & records yes Members and the data behind them People: see members by status, signups per week and top countries, then recent signups, recently active and suspended members, search from the header, open a member to suspend, restore or sign out. Records: use a common lookup or the query builder to find and correct a record safely, with a reason for private fields
Reports yes Member reports See the queue as cards with a prepared suggestion chip, open a group, read the suggestion beside the evidence, decide in the Decision bar (Dismiss, Hide, Remove content, Suspend), move between groups with Next and Previous, a swipe or J and K
Support yes Help requests from members Read, reply, add notes, take or release, change status
Backstage yes The menu page and your account Reach every other screen, switch to or link a personal account, add a passkey, sign out
Review requests, Photo reviews via Reports and Backstage The other two review queues Undo or keep an action a member asked to have reviewed (a suspended member asks at sign-in; Undo lifts the suspension and emails them), approve or reject a member cover photo, each with one click or the same Decision bar
Operations, Announcements, Feature switches via Backstage (Platform) Keep the platform running Operations: retry or discard failed background jobs, count then clean up unused files in a storage area, recompute one member's passport. Announcements: publish and preview notices. Switches: turn a feature off or on with a reason
Audit, Crashes, Team accounts via Backstage Oversight and staff Search what staff did, see frequent crashes, manage Tomoda accounts and partner workspaces

Entering Backstage, linking a personal account and any later re-authentication use one full-screen sign-in: a back chevron, the Backstage title, the Tomoda account email and role as plain text, a passkey button when this device has one (a short hint when it does not), a password field and Cancel. Leaving pops the screen, so it slides back like every other page.

Mental model

Personal account
standard, everyday member
⇄ account_links
Tomoda account
tomoda, one role
↓ step-up (Tomoda passkey or password) → short Backstage session
Backstage API
/admin/*, fresh capability gate
→
audit_logs
every read and action, Backstage actor
  • Tomoda accounts are a tomoda account type. What they can sign in with, how long their sessions last and how switching works come from the tomoda entry in the account type registry, the same framework partner accounts use.
  • Tomoda accounts are usually members too. A Tomoda account can keep their personal account and link the Tomoda account to it, then switch in from the Hub. Linking is optional: someone with only a Tomoda account signs straight in with a passkey, and can link a personal account later from the Backstage page by signing into it (a fresh step-up, then any normal sign-in of the personal account: password, Google or Apple; see Linking from the Tomoda side) and unlink it from the same place. Backstage actions are attributed to the Tomoda account; a personal account stays an ordinary member's.
  • Entering is re-proven every time. Each switch into Backstage verifies the Tomoda credential on the server, and a direct sign-in needs the Tomoda passkey. Either way the Backstage session is short: 15-minute access tokens, a 2-hour idle window and a 12-hour cap.
  • The database decides. Every Backstage request re-reads the caller's role and maps it to capabilities, so removing a role or suspending a Tomoda account takes effect on the next request.

Capabilities

A capability is one thing Tomoda accounts may see or do, named backstage.<area>.<verb> or backstage.<area>.action.<verb> (backstage.people.read, backstage.people.action.suspend, backstage.audit.read, backstage.accounts.action.manage). Roles map to capabilities in one table (backstageRoles in backend/internal/access/capabilities.go, listed on Authentication → Capabilities). A new area adds its own prefix under backstage. and grants it to roles there.

The server enforces each capability per route (the route table backstage.Routes, mounted through access.Authorizer.Require). Clients read the caller's list from GET /backstage/me and show only the screens and actions it allows; hiding a control is never the check.

Sections

Section Capability What it does
Dashboard backstage.today.read Active members, platform mix, build versions (the Dashboard also reads insights, queues and cases the role can see)
People backstage.people.read, backstage.people.action.* Find anyone by id, email or handle; profile, account state, devices and sessions; suspend, restore, sign out everywhere, undo an enforcement action
Reports backstage.reports.read, backstage.reports.action.resolve Triage report groups from the queue cards (Decision bar to decide, swipe or keys to move between groups), take enforcement actions, decide review requests
Cases backstage.cases.read, backstage.cases.action.reply Support requests from the app, the public form and email: thread, replies, internal notes, status, assignment
Data backstage.data.read, backstage.data.read_private, backstage.data.action, backstage.data.action.approve Read registered tables by field, make typed reversible changes; large changes need a second admin
Insights backstage.insights.read, backstage.insights.read_member Daily platform totals from the nightly build; one member's engagement, audited per view
Crashes backstage.crashes.read The most frequent unresolved crashes, read-only from the crash-reporting project
Ops backstage.ops.queues, backstage.ops.action.replay Background queues and failed tasks; re-run or delete a task, orphan sweep, challenge and stamp replay
Announcements backstage.announcements.read, backstage.announcements.action.publish Scheduled notices shown once as a popup on Home to members who joined before they started, written per language with English as the fallback
Switches backstage.switches.read, backstage.switches.action.set Turn a registered feature off or on for everyone, with a reason
Audit backstage.audit.read Search the audit log by actor, action, target and time
Accounts backstage.accounts.read, backstage.accounts.action.manage Tomoda tab: accounts and their links, invites, role changes, revocation
Accounts, Partners backstage.partners.read, backstage.partners.action.manage Partners tab: workspaces and their members, inviting an owner, member role changes, suspending and restoring a workspace

People shows and acts on member accounts only; Tomoda accounts appear there only for admins (backstage.accounts.action.manage) and are managed in Accounts. Tomoda accounts can't act on their own personal account.

Tomoda access lifecycle

Step Who Rule
Bootstrap Operator task backstage:bootstrap ENV=dev\|prod creates the master admin from its Secret Manager password; signing in needs that password and the code emailed to the developers mailbox
Invite Admin, with a fresh step-up Role and address; the token is shown once, stored as a hash, valid 72 hours
Accept Invitee, signed in on their personal account or signed out Proves the invited address with an emailed code and sets the Tomoda password. Signed in, the Tomoda account is linked; signed out, it stands alone and the invitee lands in Backstage
Add a passkey Tomoda accounts, inside Backstage Registered on the Tomoda account; step-up then offers it first, and it signs in without a code
Change role Admin, with a fresh step-up Never their own; never leaves zero active admins; applies on the next request
Revoke Admin, with a fresh step-up Disables the Tomoda account, drops its role, removes the link, ends its sessions

Audit

Every People read (search results by account id, person detail), every audit search, every action, every step-up and every switch into Backstage writes an audit_logs row whose actor is the Tomoda account. Reads fail rather than return data when the row can't be written, and every write is audited through the Service and fails closed. People search by email needs the full address. Audit rows survive account deletion with the reference cleared (see Data Model → Account deletion).

The app shell

Backstage is the (backstage) route group under /backstage (Dashboard, People & records, Reports, Cases, Crashes, Ops, Announcements, Switches, Audit, Access), mounted only for a Backstage session. Navigation and actions follow the capabilities from GET /backstage/me; a section the caller lacks shows a not-available state. Strings are English-only (frontend/i18n/backstage.json). Device-side session handling (separate storage, switching back, expiry fallback) is on Authentication → On the device; routes are on Routing.

Suggestions

Reports, cover photos and support cases carry a prepared suggestion, and announcements carry machine translations for the languages not written yet. They are made by jobs when an item changes, shown with the item and never applied. Staff re-run nothing and the Decision bar is unchanged. See Assist layer.