Repository navigation
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.
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).
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;signInPOSTwriteslastSignInAtto UserMetadata. -
EmailVerification (
OPTIONAL), Session, UserMetadata, UserRoles. -
TOTP + MultiFactorAuth overriding
getMFARequirementsForAuthto always require TOTP — MFA is mandatory. -
requireSuperAdmin()is the per-request gate: authenticated session →assertSuperAdmin(rolesuperadmin, tenantpublic, with asuperadminBootstrapEmailsbootstrap path) → MFA-complete check (redirect to/auth/mfa/totp) → disabled-account check.isUserDisabledfails closed on sign-in.
-
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 andSessionsSection. -
organizations/— org verification/corroboration/demo handling:CorroborationPanel,OrganizationRowActions, verification logic. -
settings/— profile + change-email forms. -
analytics/andauth/— 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 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
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/prismain 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.
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.
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.
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.
Home · Architecture · ADRs · Plans · Roadmap · Contributing · Main repo · DeepWiki · Discord
Yosemite Crew is a product of DuneXploration UG (haftungsbeschränkt). This wiki mirrors the repository; where a page and the repo disagree, the repo wins. See the Wiki Style Guide.
Product & Domain
Architecture
Applications
- Backend — Overview
- Frontend / PIMS Web — Overview
- Mobile — Overview
- Desktop PIMS Shell
- Developer Portal
- SuperAdmin
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Meta
Canonical code & docs: main repo · Auto-generated companion: DeepWiki