AD-04 System Audit Trail & Logs | Admin App Specification

Live Audit Trail & Diagnostic Event Table

Design System Parity: 100%

Action Event	Actor	Target Entity	Timestamp	Status
SUBSCRIPTION_ACTIVE	stripe_webhook_worker	company:apex_logistics	2026-08-08 14:02:11	200 OK
AUTH_MFA_CHALLENGE	admin@punchcharlie.com	session:0f9e38a2	2026-08-08 13:48:50	Verified

System & App Logs Control Room Wireflow

Click to Zoom Fullscreen

graph LR
    LogsPage[Admin Logs Page /logs] --> QueryTab{searchParams.tab}
    QueryTab -->|tab=audit or default| FetchAudit[Query company_audit_logs Table]
    QueryTab -->|tab=errors| FetchErrors[Query app_error_logs Table]
    FetchAudit --> AuditTable[Render Audit Logs Table: Action Badges & Diff Description]
    FetchErrors --> ErrorTable[Render Error Logs Table: Route, Stack & Severity Status]
    FetchErrors -->|Table Missing 42P01| MigrationNotice[Render SQL Migration Setup Alert]

Logs Page Subsystems & Data Connectors

• admin/src/app/logs/page.tsx (Server Component)
• /logs?tab=audit (Company Audit Trail)
• /logs?tab=errors (Runtime App Crash Diagnostic)

System Logs Audit Guardrails

Append-Only Integrity: Audit log tables (company_audit_logs) are append-only. Super Admin views provide read-only access to prevent tampering with historical security audit trails.

sequenceDiagram
    autonumber
    actor Admin as Security Officer
    participant Page as AdminLogsPage (/logs)
    participant Supabase as Supabase Server Client
    participant DB as PostgreSQL Database

    Admin->>Page: Request /logs?tab=audit
    Page->>Supabase: Query company_audit_logs joined with companies & profiles
    Supabase->>DB: SELECT id, action, description, old_values, new_values
    DB-->>Supabase: Return Audit Log Records
    Page->>Page: Map Action Badges (UPDATE_TIMESHEET_SETTINGS, ACTIVATE_SUBSCRIPTION)
    Page-->>Admin: Render Server-Side Audit Log Table

Component	Codebase Path / Token
Audit vs Error View Selector Tabs	admin/src/app/logs/page.tsx (Line 125)
Company Audit Log Table	admin/src/app/logs/page.tsx (Line 183)
App Crash Error Table	admin/src/app/logs/page.tsx (Line 241)
Action Badge Mappings	admin/src/app/logs/page.tsx (Line 38)

System & App Logs

Page Visual Switcher

System & App Logs Control Room Wireflow

AD-04 System Audit Trail & Logs Wireflow