Admin App Architecture & System Hub | Punch Charlie Design System

Admin App Wireflow (Super Admin Logic & Navigation)

MERMAID LOGIC

Click to Zoom Fullscreen

graph TD
    classDef auth fill:#27272a,stroke:#71717a,color:#ffffff,font-weight:bold
    classDef admin fill:#7c2d12,stroke:#f97316,color:#fff7ed,font-weight:bold
    classDef action fill:#064e3b,stroke:#10b981,color:#ecfdf5,font-weight:bold

    SignIn[AD-05 Admin Sign-in / OAuth Gate]:::auth --> AuthCheck{super_admins Table Email Match?}:::auth
    
    AuthCheck -->|Authorized| Dashboard[AD-01 Super Admin Dashboard]:::admin
    
    Dashboard --> Clients[AD-02 Client & Tenant Directory]:::admin
    Dashboard --> Support[AD-03 Global Support Desk Queue]:::admin
    Dashboard --> Audit[AD-04 System Audit Trail & Logs]:::admin
    
    Clients -->|Update Plan / Suspend| POSTClient[POST /api/clients]:::action
    Support -->|Read / Reply| ThreadView[Manage Support Thread]:::action
    Audit -->|View Logs| QueryLogs[Query company_audit_logs / app_error_logs]:::action

Admin App Sitemap & Screen Hierarchy

admin.punchcharlie.com (Super Admin Domain)

AD-01 Super Admin Platform Dashboard /admin-app/dashboard.html →
AD-02 Client & Tenant Directory /admin-app/clients.html →
AD-03 Global Support Ticket Queue /admin-app/support.html →
AD-04 System Audit Trail & Logs /admin-app/logs.html →
AD-05 Super Admin Sign-in & MFA Gate /admin-app/signin.html →

Super Admin Security & System Guardrails

Super Admin Whitelist Verification

All route access requires an email match in the database super_admins table. Non-authorized accounts redirect to /signin?error=unauthorized.

Service Role RPC Data Aggregation

Cross-tenant metric aggregation executes via stored procedures (e.g. get_all_companies_admin) bypassing standard tenant RLS boundary filters.

Workspace Suspension Enforcement

Setting is_blocked = true immediately disables employee clocks, locks owner login sessions, and revokes API access tokens for that company workspace.

Super Admin Client Plan Provisioning Sequence

sequenceDiagram
    autonumber
    actor Admin as Super Admin Operator
    participant UI as Admin Client Drawer (AD-02)
    participant API as POST /api/clients
    participant DB as Supabase Companies Table

    Admin->>UI: Select Client & Change Plan Tier (Standard / Premium)
    UI->>API: Send FormData { id, subscription_status, plan_tier, is_blocked }
    API->>DB: UPDATE companies SET plan_tier = $tier, is_blocked = $is_blocked
    DB-->>API: 200 OK Record Updated
    API-->>UI: Return Success & Trigger router.refresh()
    UI-->>Admin: Render Optimistic UI Update & Success Toast

Admin App Screen Inventory Matrix

Screen ID & Name	Route Path	Target Audience	Specification
AD-01 Platform Dashboard	/admin-app/dashboard.html	Super Admin	View Spec →
AD-02 Client & Tenant Directory	/admin-app/clients.html	Super Admin	View Spec →
AD-03 Global Support Ticket Queue	/admin-app/support.html	Super Admin / Support Lead	View Spec →
AD-04 System Audit Trail & Logs	/admin-app/logs.html	Security Officer	View Spec →
AD-05 Super Admin Sign-in & MFA Gate	/admin-app/signin.html	Super Admin Auth	View Spec →

Super Admin Portal Architecture

Page Visual Switcher

Admin App Wireflow (Super Admin Logic & Navigation)

Admin App Sitemap & Screen Hierarchy

Super Admin Security & System Guardrails

Super Admin Client Plan Provisioning Sequence

Admin App Screen Inventory Matrix

Super Admin Portal Architecture

Page Visual Switcher

Admin App Wireflow (Super Admin Logic & Navigation)

Admin App Sitemap & Screen Hierarchy

Super Admin Security & System Guardrails

Super Admin Client Plan Provisioning Sequence

Admin App Screen Inventory Matrix

Admin App Wireflow — Fullscreen Interactive View