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¶
standard, everyday member
tomoda, one role
/admin/*, fresh capability gate
every read and action, Backstage actor
- Tomoda accounts are a
tomodaaccount type. What they can sign in with, how long their sessions last and how switching works come from thetomodaentry 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.
Where to read next¶
- Endpoints, invariants and ports: Backstage service
- Account type policies, linked accounts, invites and step-up: Authentication
- Tables: Data Model