Skip to content

Backstage service

Purpose

The backstage domain (backend/internal/services/backstage/) is the server side of Backstage, the Backstage UI (see Backstage). It serves the Today stats, People (find a member, read their account, suspend, restore, sign out everywhere), report triage, the support case console, the audit viewer, Access (Tomoda accounts, invites, roles, revocation), location merge, the async worker controls (queue overview, dead-letter replay, on-demand S3 orphan sweep, stamp and challenge re-evaluation), announcements and feature switches.

Every route re-reads the caller's role from Postgres and checks one capability (see Authorization). Every read of member data and every action writes an audit_logs row under the Backstage actor.

Aggregates

One Handler, one Service (its Deps in service.go) and one Store serve every aggregate below. Each aggregate keeps its methods in its own files, and a separate store only where it owns its tables (data actions, insights, audit reads).

Aggregate Files Holds
Console handler.go, console.go, store.go Today stats, user directory, legacy status and subscription overrides, location merge
People people.go, people_handler.go Search, person detail (profile, state, devices, sessions), suspend, restore, sign out everywhere
Accounts accounts.go /backstage/me capabilities, Tomoda list, invites, role changes, revocation, invite acceptance
Partners partners.go Partner workspaces and members, inviting an owner, member role changes, suspend and restore
Cover review covers.go, covers_handler.go Cover photo queue, detail, approve and reject, cover removal from a report
Triage triage.go, triage_handler.go Report queue, group detail, decisions, enforcement, review requests, undo, member and reporter notices
Cases cases.go Support case console: queue, thread with internal notes, replies, status, assignment
Data data_registry.go, data_query.go, data.go, data_store.go, data_handler.go Data console: registry, query builder, typed reversible changes, second-admin approval
Insights insights_store.go, insights.go Nightly aggregates, the dashboard, per-member engagement
Reviews reviews.go Runs the assist review jobs (reports, cover photos, cases, announcements) and reads the stored suggestions back with each item
Crashes crashes.go Top unresolved crash issues from the crash-reporting project, read-only
Audit audit.go, audit_store.go Filtered, keyset-paged audit search
Async async.go Asynq Inspector + Client operations. Reads and enqueues audit first. Re-run, delete and run-all audit after they succeed, so an unknown queue or task is a 404 with no audit row. Only the worker's queues are reachable, and mail and deletion tasks (cleanup:s3_delete, support:send_email, legal:policy_notice) can be deleted but never re-run. Archived-task listings return type, id, retry counts and a short error class only, never the payload or full error text
Ops ops.go, ops_handler.go Announcements (Tomoda accounts authoring, the member read) and the feature switch endpoints

AccountStore doubles as the access.StandingReader behind every fresh capability gate: one primary-key read of account_type, role, is_active, is_suspended and deactivated_at, uncached.

HTTP endpoints

All /backstage routes need a JWT plus the capability in the table; the route table is backstage.Routes in routes.go, mounted with Authorizer.Require from backend/internal/wiring/router.go. Routes stay under /backstage. The group sits outside the age gate because Tomoda accounts carry no date of birth.

Method Path Capability Description
GET /backstage/me backstage.session.read Caller, current role and capabilities
* /backstage/async/* backstage.ops.queues (reads), backstage.ops.action.replay (actions) Queue overview, failed jobs (retry, discard), storage areas with a dry-run count then cleanup, per-member passport recompute (plus the older challenge and stamp replay)
GET /backstage/stats/system, /backstage/stats/daily backstage.today.read Today counters and series
POST /backstage/locations/merge backstage.catalog.action.merge Fold a duplicate place into another
GET /backstage/people/overview backstage.people.read Members by state, signups per week, top countries, linked staff, recent signups, recently active and restricted members (audited)
GET /backstage/people?q= backstage.people.read Search by id, full email address or handle prefix, at most 20 (audited) and 120 an hour per account. An incomplete address is a 400, so the search can't list addresses
GET /backstage/people/{id} backstage.people.read Profile, state, devices, sessions (audited)
POST /backstage/people/{id}/suspend backstage.people.action.suspend Suspend with a reason, end sessions
POST /backstage/people/{id}/restore backstage.people.action.restore Lift a suspension or disable
POST /backstage/people/{id}/sign-out backstage.people.action.sign_out End every session
GET /backstage/reports?status=&cursor= backstage.reports.read Report groups in one status, urgent first, 25 a page (audited)
GET /backstage/reports/{id} backstage.reports.read Group, its reports and the member's earlier actions (audited)
GET /backstage/geo-covers?status=&target=&cursor= backstage.reports.read Cover photo submissions in one status, optionally only area or place, oldest first, 25 a page (audited)
GET /backstage/geo-covers/{id} backstage.reports.read Submission, the target's current cover, its photo set, its open reports and, while pending, the review checks (audited)
POST /backstage/geo-covers/{id}/decide backstage.reports.action.resolve {outcome, note}: approve or reject
POST /backstage/geo-covers/{id}/favourite backstage.reports.action.resolve {favourite}: pick or clear an approved photo as its target's favourite
POST /backstage/reports/{id}/resolve backstage.reports.action.resolve {outcome, kind, note}: dismiss, or act; suspend also needs backstage.people.action.suspend
GET /backstage/reviews backstage.reports.read Open review requests, oldest first (audited)
POST /backstage/reviews/{id}/keep backstage.reports.action.resolve Close a review request and leave the action standing. The member is notified
POST /backstage/enforcement/{id}/undo backstage.reports.action.resolve {reason}: undo an action. A suspension is lifted (needs backstage.people.action.suspend), a content hold released. Audited with the reason
GET /backstage/cases?status=&mine=&cursor= backstage.cases.read Cases in one status, longest waiting first, 25 a page (audited)
GET /backstage/cases/{id} backstage.cases.read The case and its whole thread, internal notes included (audited)
POST /backstage/cases/{id}/messages backstage.cases.action.reply {body, internal}: reply (emailed, case to pending) or internal note
POST /backstage/cases/{id}/status backstage.cases.action.reply {status}: open, pending or solved
POST /backstage/cases/{id}/assignee backstage.cases.action.reply {take}: take or release the case
GET /backstage/data/entities backstage.data.read Registered entities, fields and actions the caller may use
POST /backstage/data/query backstage.data.read {entity, filters, cursor} public fields: 50 rows a page (audited)
POST /backstage/data/query/private backstage.data.read_private (reason header) Same body, private fields too. X-Access-Reason (percent-encoded, at least 10 characters) is required and recorded with the audited read
POST /backstage/data/actions/preview backstage.data.action Count and sample of the rows a change would touch; whether it needs approval
POST /backstage/data/actions backstage.data.action {entity, action, ids or filters, reason}: apply, or hold for a second admin above 25 rows
GET /backstage/data/actions backstage.data.read The last 50 changes
POST /backstage/data/actions/{id}/approve, /reject backstage.data.action.approve A second admin decides a held change; never the requester
POST /backstage/data/actions/{id}/undo backstage.data.action Revert an applied change
GET /backstage/insights?days= backstage.insights.read Daily platform totals over the window (default 30, at most 365), audited
GET /backstage/insights/members/{id}?days= backstage.insights.read_member One member's daily actions by verb; each view audited against the member
GET /backstage/crashes backstage.crashes.read Top unresolved crashes of the last 24 hours (audited); configured: false without a token, error when the provider can't be reached
GET /backstage/audit backstage.audit.read Filter by actor, action, resource_type, target, since, until; cursor pages
GET /backstage/accounts/tomoda, /backstage/accounts/tomoda/invites backstage.accounts.read Tomoda accounts with links; recent invites
POST /backstage/accounts/tomoda/invites backstage.accounts.action.manage (step-up) Create an invite; returns the one-time token
POST /backstage/accounts/tomoda/invites/{id}/revoke backstage.accounts.action.manage (step-up) Withdraw a pending invite
PATCH /backstage/accounts/tomoda/{id}/role backstage.accounts.action.manage (step-up) Change a Tomoda role
POST /backstage/accounts/tomoda/{id}/revoke backstage.accounts.action.manage (step-up) Disable, unlink and sign out a Tomoda account
GET /backstage/accounts/partners, /backstage/accounts/partners/{id} backstage.partners.read Workspaces with member counts; one workspace with members and invites (audited)
POST /backstage/accounts/partners/{id}/invites, .../invites/{invite_id}/revoke backstage.partners.action.manage (step-up) Invite an owner of the workspace; withdraw an invite
PATCH /backstage/accounts/partners/{id}/members/{user_id}/role backstage.partners.action.manage (step-up) Change a member's role; the last owner stays
POST /backstage/accounts/partners/{id}/suspend, .../restore backstage.partners.action.manage (step-up) Suspend a workspace (every member's next partner request answers 403) or lift it

Invites, their acceptance, links, step-up and a Tomoda account linking its own personal account (POST/DELETE /auth/links/personal) are the auth domain's generic endpoints (see Authentication → Invites); Access is the caller that creates tomoda invites.

Refusals carry stable error codes (ALREADY_RESOLVED, INTERNAL_TARGET, SELF_TARGET, LAST_ADMIN, LAST_OWNER, STATUS_UNCHANGED, EMAIL_IN_USE, EMAIL_DOMAIN, INVITE_NOT_FOUND, plus STEP_UP_REQUIRED from the gate) so clients can word each one; the map is writeBackstageError in people_handler.go.

Invariants

  • People acts on members only. Suspend, restore and sign out refuse tomoda accounts (Tomoda accounts are managed in Accounts) and the actor's own linked personal account. Search and detail leave Tomoda accounts out (detail answers 404) unless the caller holds backstage.accounts.action.manage.
  • Every write audits through the Service and fails closed. Handlers never call the audit writer. Service.record is the one helper, and a failed audit write stops the action (location merge audits before the hard delete). Reads of Tomoda accounts and invites are audited like the rest.
  • People search and private reads are throttled in the route table (limited(...) in routes.go), not by matching paths.
  • The orphan sweep ignores objects younger than 48 hours, since uploads wait unattached until their record is filed.
  • No read without its audit row. People search, person detail and audit search return an error rather than data when the audit write fails. Search rows record which account ids came back, not the query text.
  • Account changes need a fresh step-up. Every capability flagged step-up (backstage.accounts.action.manage, backstage.partners.action.manage) spends a single-use sensitive step-up token, sent in the X-Step-Up-Token header and spent by the gate before the handler runs, proven by the acting admin (see Step-up and switching). Validation failures are checked before the token is spent.
  • No self-changes, never zero admins. An admin cannot change or revoke their own Tomoda account, and a change that would leave no active admin is refused.
  • Role changes apply on the next request. The fresh gate reads the role every time, so a role change needs no session reset. Revocation also ends the Tomoda account's sessions.
  • Invites store only a hash. The token is returned once at creation and expires after 72 hours. Acceptance proves the invited address with an emailed signup code, claims the invite atomically, and releases the claim if account creation fails. The role always comes from the invite.
  • Audit rows outlive accounts. audit_logs.user_id is ON DELETE SET NULL; the purge pseudonymizes the deleted account's own rows first.
  • Audit rows are append-only. A trigger refuses UPDATE and DELETE on audit_logs, except the foreign key clearing user_id and the two maintenance paths (the retention prune and the account-deletion scrub), which opt in per transaction with tomoda.audit_maintenance.

Report triage

Member reports arrive through the report service; triage is here because only Tomoda accounts read and decide them.

  • One decision per group. Resolve claims the open group in the same transaction that records the action, so a second decision gets ALREADY_RESOLVED and changes nothing.
  • Decisions fit the target. Content kinds (hide_content, remove_content) need a moment, message or event; events are hidden, never removed; every action needs a member to act on. Validation runs before the group is claimed.
  • Never about yourself or Tomoda accounts. A decision or undo whose target member is the actor's own linked personal account, or a Tomoda account, is refused before anything is claimed.
  • Recorded before applied. The audit row is written right after the decision commits; a failure applying it afterwards is logged and returned, and the decision stays recorded.
  • Suspend goes through People. A suspend decision needs backstage.people.action.suspend as well and uses the People suspend path (without recording a second action), so a report never suspends a Tomoda account or the actor's own personal account. A suspension from the People screen records its own enforcement action, so it can be reviewed and undone like any other. Restoring a member marks their standing suspensions undone.
  • Dismissing restores. A dismissal restores content an automatic rule hid.
  • Notices name no one. The target member gets moderation.action (and moderation.review_decided after a review); each reporter gets moderation.report_outcome. No notice carries a Backstage actor or note.
  • Reviews and undo are one person. A member's review request (including a suspended member's, filed at sign-in) is decided by any one Tomoda account: undo the action (same capability that took it, a reason required, the request closes as undone) or keep it. Undo reverses the action first, then lifts a suspension only if the account is suspended and no other suspension stands. Content holds are released in the reversal's transaction. Either decision notifies the member (moderation.review_decided), and a suspension decision also emails them.
  • A failed cover removal leaves the group open. Clearing the cover runs before the group closes and is safe to repeat, like a suspension.
  • Suggestions only advise. A report group's stored suggestion comes from the report_triage job and never decides or acts; see Assist.
  • Every read and decision is audited under the Backstage actor (queue reads record how many groups came back).

Support cases

The support service owns cases, email and threading; the console here adds the capability gates and the audit trail. Every queue read, case read, reply, note, status change and assignment writes an audit_logs row (support_case) under the Backstage actor. Replies go through support.Service.TeamReply, so threading and the member notice behave the same wherever a reply comes from.

Data console

A registry (data_registry.go) declares every readable entity: its table, its fields with a type, which fields are private, and its typed actions. Nothing from a request reaches SQL except as a bind parameter: entity, field and comparison names are looked up in the registry, values are parsed for the field's type (UUID, integer, boolean, time, enum member) and contains escapes LIKE wildcards. All columns are qualified with a table alias and cast to text for one row shape; pages are newest first by keyset on the raw sort column (rows without a timestamp last), served by (created_at, id) indexes. A read runs in a read-only transaction under an 8 second statement timeout.

  • Private fields (email addresses, message content, captions, descriptions, dates of birth, case subjects and addresses, report snapshots, and the fields that link a row to a member or place: user, host, chat and requester ids, target user, city) need backstage.data.read_private and a reason of 10 to 500 characters; the read and its reason go to the audit log. A private read is limited to 60 an hour per account. Entities flagged needs_case (chat messages) also need the id of the support case or report group the read is for, checked to exist and recorded with the reason.
  • Typed actions set one text or enum field to a fixed value (for example a moment's owner_visibility to private; visibility itself is derived, so a change never lifts a moderation hold). Applying records each row's previous value in data_actions.before; undo puts it back only on rows that still hold the value the change set.
  • Selection. A change targets explicit ids or the rows a filter matches now, at most 1,000; a filter with no condition is refused, so no change runs on a whole table.
  • Second admin. More than BulkApprovalThreshold (25) rows, counting the rows the same admin changed alone in the last hour (counted in the applying transaction under a per-requester advisory lock, so concurrent requests can't each slip under), is held as pending until another admin with backstage.data.action.approve approves or rejects it; the requester can't decide their own. Approval re-reads the held ids inside the transaction that applies it.
  • Undo works for 24 hours after a change applied, and is refused once a newer change touched any of the same rows. Undoing a change of more than 25 rows takes two admins: the first request moves it to undo_pending, a different admin carries it out.
  • Everything is audited under data:<entity>: reads (row count, the returned row ids, and each filter with its value; free-text values as a short hash), previews, changes with their reason, approvals, rejections and undos.

Insights

cron:insights_build runs nightly and writes one row per day, metric and dimension into insights_daily: active members (distinct actors in activity_events), actions by verb, standard signups, moments, events, chat messages, reports and support cases. It also writes insights_member_daily, one row per active member per day with their actions by verb. A day is rebuilt whole (delete then insert in one transaction, committed per day), so reruns are safe and a failure keeps the days already built; the job fills any day missed in the last 14 and trims member rows after 180 days. Member rows cascade with the account.

The dashboard reads only the aggregates and is audited as insights. A per-member view needs backstage.insights.read_member and writes an audit row against that member (resource_type user).

Suggestions in Backstage

Backstage prepares suggestions with the assist layer and shows them beside the evidence. No endpoint runs assist and nothing re-runs on demand. A job runs when an item changes:

Item Trigger Task Where staff see it
Report group A report is filed on it report_triage ai_review on the group detail, ai_reviews by id on the queue page
Cover photo It is submitted photo_review ai_review on the submission detail, ai_reviews on the queue page
Announcement It is created or edited translate suggested_texts for the languages not written yet, filled into the editor for review

backstage.ReviewTriggers satisfies the report and geo cover ReviewTrigger ports by queueing an assist:review job, and Service.RunReview is the job body (asynchandlers.AssistReviewer). Member names, handles, emails and phone numbers are masked before anything is sent. A child safety report, or any content a deterministic check flags as possibly concerning a child, is never sent, and the item stores a fixed "needs a person" record. A suggestion never decides: the Decision bar is unchanged and a translation only reaches members after staff save it in the editor. Reads of the item are audited as before, so the suggestion adds no separate read.

Switching assist off (the assist feature switch) stops every task at once. The review model's daily token budget is separate and stops calls for the rest of the UTC day.

Crashes

platform/crashes reads the crash-reporting project (Sentry's issues API) with a read-only token: the 25 most frequent unresolved issues of the last 24 hours, cached for a minute. Nothing is written back. Without CRASHES_API_TOKEN, org and project the view says it isn't connected; a provider failure shows as unavailable instead of an error page.

Announcements

An announcement is one row in announcements: a severity (info or warning), a window, and its copy as JSON keyed by language (texts, the email locales such as en, ja, zh-Hans). English is required; a language left empty is dropped and its members see English. Titles are up to 80 characters, messages up to 600, plain text only. A window ends in the future and runs at most 30 days. Withdrawing sets withdrawn_at and is final. In the app, severity only picks the copy: info is "What's new" and warning is "Maintenance" (which shows its window as time chips). The member read returns an announcement only to an account created before its window started (users.created_at < starts_at), so new members never see older notices. The app shows one as a popup on Home, at most once per app open (maintenance first), and remembers on the device that it was seen. The editor's default window is seven days.

Feature switches

platform/switches holds the registry: each switch's name, description, default and whether the app may read it. Tomoda overrides live in feature_switches (value, reason, who, when). Each process caches the overrides for 15 seconds, so a change reaches every server within that time; a failed reload keeps the last known values, or the defaults before the first load. An unregistered name reads off and can't be set.

Switch Default Effect when off
support.public_form on POST /support/contact answers 503; in-app cases still work
problem_report.shake on The app stops opening the problem sheet on shake; the other entry points stay

Adding a switch is a code change: a registry entry plus the check where the feature runs. The server enforces every switch itself; the app's read only hides controls.

Cover review

Member photos offered for areas and places arrive through the geo cover service; review is here because only Tomoda accounts decide them. covers.go and covers_handler.go audit every queue read, detail read and decision.

  • Approve adds to the set. The photo is normalized, uploaded under a content-hashed key and joins the target's approved set; the cover is the favourite, else the newest (a place's curated cover still outranks member photos). A member cover stores no author and shows no attribution line (the Tomoda member license value only marks it as a member photo; curated stock covers keep their required attribution), and a replaced object is removed once nothing else references it.
  • Checks, never auto-rejects. The detail shows the photo's EXIF distance from the target, duplicate flags and a reminder to reject photos where people are the subject. The queue screen labels each item Area or Place and filters by it.
  • Moment-sourced photos are re-checked. Approve confirms the source moment is still live; otherwise it returns 422 and only a rejection follows.
  • Reject closes. The staged photo is deleted; the member may submit another.
  • One decision per submission. A second decision gets 409. A photo that can't be read or decoded returns 422 and can only be rejected.
  • Cover reports. A report group on a cover offers dismiss, or remove_content, which clears the place's cover. No enforcement action is recorded since a cover has no owner, and only the reporters are notified.

Dependencies (deps.go)

Port Satisfied by Used for
AuditLogger platform/audit.Service Every audited read and action
ReportQueue report.Store Queue, group detail, resolve with its content change, undo
GeoCovers geocover.Service Cover review queue, approve and reject, cover removal
notify.Notifier notification service Member and reporter notices
CaseStore, CaseReplier support.Store, support.Service Case console reads and Tomoda replies
AssetURLs platform/assets.Service Signed screenshot links
CrashSource platform/crashes.Client The crash list
AssistRunner platform/assist Backstage scope Runs Backstage assist tasks, nil in tests that don't use it
AIReviews platform/assist.Store Reads the stored suggestions for items
ReviewEnqueuer async.Client Queues assist:review for an announcement save
SwitchBoard platform/switches.Service Listing, setting and publishing feature switches
AnnouncementStore backstage.NewStore Announcements
DataStore backstage.NewDataStore (pgx) Registry-built reads and data changes
InsightsStore backstage.NewInsightsStore Nightly aggregates; backstage.Service is also the async InsightsBuilder
SessionTerminator, AccountStatus auth.AuthService Ending sessions; dropping the cached usability verdict on restore
AccountLinks auth.LinkService Unlinking and resolving linked accounts
Invites auth.InviteService Creating, listing and revoking tomoda and partner invites
UserFinder user.UserStore /backstage/me
LocationAdmin location service Merge

Location merge

Auto-dedup (provider-id match plus spatial and name fuzz, see Locations → Dedup story) catches most duplicates at write time. When it misses, most often the same physical place under different display names, Tomoda accounts fold the two together with POST /backstage/locations/merge and a body of source_id, target_id and an optional reason.

The merge runs in a transaction:

  1. Rewrite every cross-reference, driven by the locationFKRewrites manifest in backend/internal/services/location/location_store.go. The startup verifier (VerifyMergeCoverage) fails the boot if a location_id FK is missing from it.
  2. Append source's (provider, provider_id) and its own secondary providers to target's secondary_providers, deduped, so target stays reachable by either id.
  3. Hard-delete source. Nothing alive points at it any more; the forensic trail is the audit_logs row.
  4. Clear the provider-pair cache entries on the surviving row.

The endpoint refuses source_id == target_id and already-merged sources.

Audit log vs. activity log

audit_logs (platform/audit) activity_events (Activity)
Purpose Forensic record of Tomoda and security-sensitive actions Interaction firehose that feeds personalization
Write path Direct synchronous write POST /activity/events, folded by the rollup cron
Read access Backstage audit viewer (backstage.audit.read) The rollup and offline training

Where to look