Skip to content

SuperAdmin

Ankit Upadhyay edited this page Aug 25, 2026 · 2 revisions

SuperAdmin

SuperAdmin is an internal governance/admin panel in a separate repository. It uses SuperTokens for auth and all auth-side state (roles, metadata, the audit log), and it now also carries its own Prisma-backed Postgres for governance data - isolated from the product databases (see Persistence below). Canonical code: apps/admin in the SuperAdmin repo. Its own decision log: SuperAdmin ADR-0001.

Framework

Next.js 16 (App Router, Turbopack dev), React 19, TypeScript strict, Tailwind 4, Jest + Testing Library + jest-axe. The app consumes the repo's @superadmin/database workspace package (the Prisma client - see Persistence below). No client state library - local React state, Server Components, and URL params. App shell under src/app/ (layout.tsx, route group (routes)/(dashboard)/…, auth catch-all app/auth/[[...path]]/page.tsx, API routes under app/api/, and a SuperTokens provider component).

Auth — SuperTokens (mandatory MFA)

src/app/config/backend.ts (backendConfig()) initializes the recipes and the authorization gate:

  • EmailPassword with public self-registration disabled (signUpPOST: undefined — closes a bootstrap-email takeover vector); sign-in blocks disabled accounts; signInPOST writes lastSignInAt to UserMetadata.
  • EmailVerification (OPTIONAL), Session, UserMetadata, UserRoles.
  • TOTP + MultiFactorAuth overriding getMFARequirementsForAuth to always require TOTP — MFA is mandatory.
  • requireSuperAdmin() is the per-request gate: authenticated session → assertSuperAdmin (role superadmin, tenant public, with a superadminBootstrapEmails bootstrap path) → MFA-complete check (redirect to /auth/mfa/totp) → disabled-account check. isUserDisabled fails closed on sign-in.

Feature areas (src/app/features/)

  • audit/ — the audit log (see below): store.ts, audit.ts, types.ts, filter.ts, csv.ts, AuditTable.tsx, AuditTimeline.tsx.
  • users/ — user management: UsersTable, UserRowActions, delete/disable/verify-email/reset-MFA/role actions, CSV export, per-user [id]/ pages and SessionsSection.
  • organizations/ — org verification/corroboration/demo handling: CorroborationPanel, OrganizationRowActions, verification logic.
  • settings/ — profile + change-email forms.
  • analytics/ and auth/ — dashboard analytics and auth barrels.

The feature set has since grown beyond this original list; src/app/features/ on main also holds ap/ (ActivityPub directory/licensing), approvals/, consent/, contact/, crm/, health/, invites/, and social/.

The audit log (SuperTokens UserMetadata)

The audit trail is a single append-only record in SuperTokens UserMetadata under a reserved id superadmin:audit-log, key events (src/app/features/audit/store.ts). recordAuditEvent() prepends via prependCapped (cap 250) and writes back; it's best-effort and non-blocking — failures are caught so a failed audit write never blocks the privileged action it records. AuditAction covers user delete/disable/enable/email/MFA/session events, role grant/revoke, and org verify/suspend/reactivate. Full decision, including the accepted trade-offs (no compare-and-swap, advisory-not-authoritative, 250-cap): SuperAdmin ADR-0001.

flowchart LR
    ACT["Admin action<br/>(disable user, change role...)"] --> REC["recordAuditEvent()"]
    REC -->|read-modify-write| UM["SuperTokens UserMetadata<br/>id: superadmin:audit-log"]
    UM --> CAP["prependCapped (max 250)"]
    REC -. "best-effort: errors swallowed,<br/>never blocks the action" .-> ACT
Loading

Persistence

The panel's persistence is split across two stores, both isolated from the product databases:

  • SuperTokens core holds all auth-side state - users, sessions, roles, disabled flags, last-sign-in, and the append-only audit log in UserMetadata. That audit-log decision (including its accepted trade-offs) is what SuperAdmin ADR-0001 documents.
  • Its own Postgres, via Prisma (packages/database/prisma in the SuperAdmin repo). The migration history covers a consent ledger (consent subjects/events), contact leads (public contact-form intake), data requests, and ActivityPub federation licensing and directory listings (license tokens issued to verified organizations so self-hosted instances can federate with the cloud, plus a directory of federated instances).

An earlier iteration of the panel deliberately had no database at all; that constraint was lifted when the governance features above needed durable relational storage. The Prisma database is the panel's own - it does not read or write the product's databases.

Deployment

The panel deploys via AWS Amplify: amplify.yml at the repo root is the build spec, and docs/deploy.md is the runbook (including the rule that Prisma migrations run in the build, on main only). It is hosted at admin.yosemitecrew.com.

Integration with the monorepo backend

The product backend mirrors public contact-us submissions (the /contact-us and accessibility-report forms) into the panel's CRM intake endpoint: apps/backend/src/services/superadmin-contact.service.ts forwards the submission best-effort (never blocking the visitor; the product database stays the source of truth), authenticated by a shared secret header. It is configured by the SUPERADMIN_CONTACT_INTAKE_URL / SUPERADMIN_CONTACT_INTAKE_KEY variables listed in apps/backend/.env.example; when either is unset, mirroring is simply off.

Governance & plans

SuperAdmin follows Yosemite-Crew governance but scopes with its own list. The original production-grade blueprint, Plans: Super Admin, is now a historical design document superseded by the shipped app; the support-queue design is in Plans: Support Chat.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally