Admin App — Data Model
The admin app stores no client-side state of its own; it’s a window onto existing tables.
audit_logs (libs/db/src/lib/schema/admin.ts)
| Column | Type | Notes |
|---|---|---|
id | uuid PK | Row identity. |
actor_clerk_id | varchar | Clerk id of the human/agent that performed the action. |
action | varchar | Action label (e.g. org.update_tier, payment.refund, agent.workouts.create). |
resource | varchar | Resource type (organization, payment, workout, …). |
resource_id | varchar nullable | Resource id when applicable. |
metadata | jsonb | Free-form context. Carries adminAction: true for admin-interceptor writes, agent: true for agent writes, impersonatedUserId, ip, userAgent, reason, etc. |
created_at | timestamp tz | Sort key. |
Indexed by (actor_clerk_id, created_at) and (resource, resource_id) for the admin audit list / drill-in queries.
Tables read (admin views)
| Table | Read by |
|---|---|
organizations | Org list + detail. |
memberships, users | Members and cross-org user search. |
subscriptions, plans, payment_transactions | Billing inspection, payments. |
platform_subscriptions, platform_transactions | Platform billing. |
leads, platform_leads | Lead pipelines. |
import_jobs, export_jobs | Job dashboards. |
audit_logs | Audit log list. |
ai_usage_daily, ai_conversations, ai_tool_executions | Costs / observability dashboards (agent slice). |
cancellation_requests | Billing inspection. |
Redis keys
platform-admin:<clerkId>— TTL 300s — caches theprivateMetadata.platformRolelookup performed byPlatformAdminGuard.
External
- Clerk’s user
privateMetadata.platformRoleis the source of truth for admin access. Updates land via Clerk dashboard or via the SDK. - PostHog captures every interceptor-driven audit row as an
admin.<action>event. - Sentry tags
admin.*actions so investigation pivot from an exception → audit log is one click.