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
tomodaaccounts (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 holdsbackstage.accounts.action.manage. - Every write audits through the Service and fails closed. Handlers never call the audit writer.
Service.recordis 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(...)inroutes.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-usesensitivestep-up token, sent in theX-Step-Up-Tokenheader 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_idisON 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 clearinguser_idand the two maintenance paths (the retention prune and the account-deletion scrub), which opt in per transaction withtomoda.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_RESOLVEDand 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
suspenddecision needsbackstage.people.action.suspendas 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(andmoderation.review_decidedafter a review); each reporter getsmoderation.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_triagejob 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_privateand 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 flaggedneeds_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_visibilitytoprivate;visibilityitself is derived, so a change never lifts a moderation hold). Applying records each row's previous value indata_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 aspendinguntil another admin withbackstage.data.action.approveapproves 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 licensevalue 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
422and 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 returns422and 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:
- Rewrite every cross-reference, driven by the
locationFKRewritesmanifest inbackend/internal/services/location/location_store.go. The startup verifier (VerifyMergeCoverage) fails the boot if alocation_idFK is missing from it. - Append source's
(provider, provider_id)and its own secondary providers to target'ssecondary_providers, deduped, so target stays reachable by either id. - Hard-delete source. Nothing alive points at it any more; the forensic trail is the
audit_logsrow. - 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¶
backend/internal/services/backstage/routes.go: the route tablebackend/internal/wiring/router.go: mounts the route tables withAuthorizer.Requirebackend/internal/access/: capability registry, role tables, the authorizer and the gatebackend/internal/access/accounttypes.go: the account type registrybackend/internal/services/auth/link_service.go,invite_service.go: step-up, switching, linked accounts and invitesbackend/internal/platform/audit/: the audit writer