Admin Analytics Dashboards

The Admin Dashboard exposes five analytics sub-panels that consume aggregation APIs from the murchases, blogs, media, search, and alerts subgraphs. All panels require the PLATFORM_ADMIN role, which is automatically assigned to Organization Owners and Admins.

Architecture Overview

┌──────────────────────────────────────────────────────────┐
│  Admin Dashboard  (/admin)                               │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│  │Overview│ │ Users  │ │ Trash  │ │History │ │Analyti.│ │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
│                 ▼                                ▼       │
│        UserListingPanel         Revenue│Blog│Media│Search│Alerts │
│        (nodes subgraph)           ┌──────────┬─────────┐ │
│                                   │ Revenue  │  Blog   │ │
│                                   │Analytics │Analytics│ │
│                                   ├──────────┼─────────┤ │
│                                   │ Media    │ Search  │ │
│                                   │Analytics │Analytics│ │
│                                   ├──────────┴─────────┤ │
│                                   │  AlertsAnalytics   │ │
│                                   └────────────────────┘ │
└──────────────────────────────────────────────────────────┘
           │               │              │
     adminUsers    revenueByDay    blogPostsByDay
     adminUser     orderVolume     blogEngagement
     adminCount    entityCounts    blogStatus
                   topMalets       topAuthors

Access Control Pipeline

Analytics queries use a two-layer auth model:

1. Gateway Role Injection — The auth service's /auth/validate endpoint returns is_privileged: true for users with an OWNER or ADMIN role in the org_members table. The gateway maps this to role: 'PLATFORM_ADMIN' in the user header forwarded to subgraphs.

2. Subgraph Runtime Check — Each analytics resolver calls assertPlatformAdmin(actor), which verifies actor.role === 'PLATFORM_ADMIN'. Unauthorized requests receive a ForbiddenException.

// Gateway auth.context.ts — role injection
ctx.user = {
  id: data.user_id,
  username: data.username,
  email: data.email,
  ...(data.is_privileged ? { role: 'PLATFORM_ADMIN' } : {}),
};

Query Layer

All analytics queries are centralized in src/lib/queries/adminAnalytics.ts with full TypeScript interfaces. The file exports 11 queries across three subgraphs:

Nodes Subgraph (User Listing)

Murchases Subgraph (Revenue)

Blogs Subgraph (Content)

Component: UserListingPanel

File: src/lib/components/admin/UserListingPanel.svelte

A paginated user management table with:

• Debounced search (300ms) across name, email, and username
• Sortable columns: CREATED_AT, DISPLAY_NAME, EMAIL with ASC/DESC toggle
• Cursor pagination: Load More with first/after relay-style pagination
• Detail drawer: Slide-in panel showing full user profile + UserActivityStats grid

query GetAdminUsers($first: Int, $after: String, $filter: AdminUserFilter) {
  adminUsers(first: $first, after: $after, filter: $filter) {
    edges {
      node {
        id displayName email avatarUrl createdAt isPrivate
        activityStats {
          followersCount followingCount collectionsCount
          ordersCount bookingsCount blogPostsCount
        }
      }
      cursor
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

State Management

The component uses Svelte 5 runes for reactive state:

let users = $state<AdminUserNode[]>([]);
let totalCount = $state(0);
let endCursor = $state<string | null>(null);
let hasNextPage = $state(false);
let search = $state('');
let sortBy = $state<'CREATED_AT' | 'DISPLAY_NAME' | 'EMAIL'>('CREATED_AT');
let sortOrder = $state<'ASC' | 'DESC'>('DESC');

Component: RevenueAnalytics

File: src/lib/components/admin/RevenueAnalytics.svelte

Revenue and Murchase volume dashboard with:

• KPI cards: Total Revenue, Total Murchases, Average Murchase Value, Platform Entities — each with a colored top accent bar
• Date range picker: 7d / 30d / 90d / 1y segment control
• Currency filter: Optional text input to scope by currency code (e.g., ZAR)
• Charts: Revenue bar chart + Order volume line chart using AdminChart
• Entity breakdown: Inline pills showing Malets, Products, Services, Users, and order-status counts
• Leaderboard: Top Malets by Revenue table with medal emojis (🥇🥈🥉)

Data Flow

RevenueAnalytics.svelte
  ├─ Promise.allSettled([
  │    revenueByDay(filter)      → KPIs + revenue chart
  │    orderVolumeTrends(filter) → volume line chart
  │    platformEntityCounts()    → entity breakdown pills
  │    topMaletsByRevenue(10)    → leaderboard table
  │  ])
  └─ Graceful partial rendering (allSettled, not all)

Component: BlogAnalytics

File: src/lib/components/admin/BlogAnalytics.svelte

Blog content analytics dashboard with:

• KPI cards: Total Views, Total Likes, Avg Views/Post, Avg Likes/Post
• Post summary pills: Total posts, Published count, Draft count
• Charts: Post volume bar chart + CSS donut status breakdown (Published/Draft/Archived/Deleted with color-coded segments)
• Malet filter: Dropdown scoped to owned Malets, passed from parent
• Leaderboards: Top Authors table + Top Posts by Views table

Donut Chart

The status breakdown uses raw SVG <circle> elements with stroke-dasharray and stroke-dashoffset for a performant, dependency-free donut:

{#each statusBreakdown as segment, i}
  <circle
    cx="18" cy="18" r="15.9"
    stroke={STATUS_COLORS[segment.status]}
    stroke-dasharray="{pct} {100 - pct}"
    stroke-dashoffset={-cumulativeOffset}
    transform="rotate(-90 18 18)"
  />
{/each}

Analytics Sub-Tab Navigation

The Analytics tab uses a lightweight sub-tab switcher rather than full routing:

let analyticsSubTab = $state<'revenue' | 'blog' | 'media' | 'search' | 'alerts'>('revenue');

<div class="analytics-sub-tabs">
  <button class:active={analyticsSubTab === 'revenue'}>Revenue</button>
  <button class:active={analyticsSubTab === 'blog'}>Blog</button>
  <button class:active={analyticsSubTab === 'media'}>Media</button>
  <button class:active={analyticsSubTab === 'search'}>Search</button>
  <button class:active={analyticsSubTab === 'alerts'}>Alerts</button>
</div>

{#if analyticsSubTab === 'revenue'}
  <RevenueAnalytics />
{:else if analyticsSubTab === 'blog'}
  <BlogAnalytics malets={malets} />
{:else if analyticsSubTab === 'media'}
  <MediaAnalytics malets={malets} />
{:else if analyticsSubTab === 'search'}
  <SearchAnalytics />
{:else if analyticsSubTab === 'alerts'}
  <AlertsAnalytics />
{/if}

Error Handling

All five analytics components use the same resilient pattern:

• Promise.allSettled for parallel queries — partial data renders even if one query fails
• Error banner with retry button
• Loading spinner per-component
• Graceful empty states when no data is returned

File Map

Related

• Workspaces & The Tower — Tower architecture, all 5 analytics sub-tabs, access control, navigation
• Media Analytics Dashboard — Dedicated Media sub-tab developer guide
• Alerts & Resilience — Backend alerts subgraph, DLQ, delivery channels
• Analytics Aggregation API — Backend revenue, Murchase volume, and entity count API reference
• Blog Analytics API — Backend post volume, engagement, and author ranking API reference
• Search Engine Administration — Backend search operations powering the Search sub-tab
• Edit History Audit Trail — Field-level diff viewer for Products, Services, and Blog Posts
• Custom RBAC — PLATFORM_ADMIN role and MANAGE_ANALYTICS permission definitions
• Organization & Malet Management — Organization context and x-org-id header mechanics
• Alert Templates — Email/SMS template maker in the Admin Dashboard Templates tab
• Search Configuration — Per-vertical synonym management and Meilisearch index reconciliation
• Payments History — Paginated Murchase table with filtering and detail drawer
• Inventory & Deprecation Tracking — Product stock health monitoring and deprecated field usage tracking
• Platform Admin Provisioning — How Tower access is controlled via dedicated platform_admins table and invite-chain