Admin Dashboard

Admin & Developer Suite Development

This skill helps you extend the admin dashboard and build internal tools following the established patterns.

Architecture Overview

/admin     - Admin Dashboard (user metrics, access control, audit)
/dev       - Developer Portal (docs, code browser, feature map) [PLANNED]
/ops       - Operations Console (infrastructure, logs, incidents) [PLANNED]

See docs/ADMIN-DEVELOPER-SUITE.md for the full design specification.

Current Admin Dashboard Structure

Location: src/app/admin/page.tsx

Existing Tabs

| Tab | Purpose | Data Source | |-----|---------|-------------| | Overview | Quick stats (users, check-ins, messages) | /api/admin/stats | | Funnel | User engagement waterfall | /api/admin/stats | | Page Views | Analytics by page path | /api/admin/stats | | Users | User roster with activity | /api/admin/stats | | Access Requests | Pending/approved/denied requests | /api/admin/access-requests | | Allowed Emails | Email whitelist management | /api/admin/allowed-emails | | Email Templates | Preview system emails | Local data |

Planned Tabs (from design)

| Tab | Purpose | Status | |-----|---------|--------| | Production Health | API latency, Core Web Vitals | Pending | | Error Tracking | HIPAA-safe error aggregation | Pending | | External Services | Anthropic, DB, Push status | Pending | | AI Analytics | Conversation metrics, tokens | Pending | | Audit Logs | HIPAA compliance viewer | Pending |

Adding a New Admin Tab

1. Create the Tab Content Component

// In src/app/admin/page.tsx, add a new tab component

function ProductionHealthTab() {
  const [metrics, setMetrics] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchMetrics() {
      const res = await fetch('/api/admin/metrics');
      const data = await res.json();
      setMetrics(data);
      setLoading(false);
    }
    fetchMetrics();
  }, []);

  if (loading) return Loading...;

  return (
    
      
        
        
        
        
      
      {/* More content */}
    
  );
}

2. Add the Tab to the Tab List

const tabs = [
  { id: 'overview', label: 'Overview' },
  { id: 'health', label: 'Production Health' }, // NEW
  { id: 'funnel', label: 'Funnel' },
  // ...
];

3. Add the Tab Content Renderer

function renderTabContent(tabId: string) {
  switch (tabId) {
    case 'overview':
      return ;
    case 'health':
      return ; // NEW
    // ...
  }
}

Creating Admin API Endpoints

Pattern: Admin Stats Endpoint

// src/app/api/admin/metrics/route.ts
import { requireAdmin } from '@/db/secure-db';
import { createRateLimiter } from '@/lib/rate-limit';
import { logAdminAction } from '@/lib/hipaa/audit';

const rateLimiter = createRateLimiter({
  windowMs: 60000,
  maxRequests: 60,
  keyPrefix: 'admin:metrics'
});

export async function GET(request: Request) {
  // 1. Check admin access
  const admin = await requireAdmin();
  if (!admin) {
    return Response.json({ error: 'Forbidden' }, { status: 403 });
  }

  // 2. Apply rate limiting
  const rateLimitResult = await rateLimiter.check(admin.id);
  if (!rateLimitResult.allowed) {
    return Response.json(
      { error: 'Rate limit exceeded' },
      { status: 429, headers: rateLimitResult.headers }
    );
  }

  // 3. Log admin action
  await logAdminAction(
    admin.id,
    AuditAction.ADMIN_STATS_VIEW,
    'metrics',
    null
  );

  // 4. Fetch and return data
  const metrics = await getAPIMetrics();
  return Response.json(metrics);
}

Key Patterns

StatCard Component

function StatCard({
  label,
  value,
  trend,
  status
}: {
  label: string;
  value: string | number;
  trend?: 'up' | 'down' | 'neutral';
  status?: 'good' | 'warning' | 'error';
}) {
  return (
    
      {label}
      {value}
      {trend && }
      {status && }
    
  );
}

Data Fetching Pattern

// Use SWR or React Query for real-time updates
import useSWR from 'swr';

function useAdminMetrics() {
  const { data, error, isLoading } = useSWR(
    '/api/admin/metrics',
    fetcher,
    { refreshInterval: 30000 } // Refresh every 30s
  );

  return { metrics: data, error, isLoading };
}

HIPAA-Safe Error Display

// Never show user-specific error details
function ErrorList({ errors }: { errors: AggregatedError[] }) {
  return (
    
      {errors.map(error => (
        
          {error.type}
          {error.path}
          {error.count} occurrences
          {error.affectedUsers} users
          {/* NO user IDs, NO error messages with PHI */}
        
      ))}
    
  );
}

Database Tables for Admin Features

Existing tables:

• adminUsers - Admin role assignments
• allowedEmails - Email whitelist
• accessRequests - Access request queue
• auditLog - HIPAA audit trail
• pageViews - Navigation analytics

Planned tables (from design):

• api_metrics - API timing data
• app_errors - Aggregated errors
• service_health - External service status
• conversation_analytics - AI chat metadata
• incidents - Incident tracking

Access Control

// Always use requireAdmin() for admin routes
import { requireAdmin } from '@/db/secure-db';

// For super-admin only features
const admin = await requireAdmin();
if (admin.role !== 'super_admin') {
  return Response.json({ error: 'Super admin required' }, { status: 403 });
}

Testing Admin Features

// Mock admin authentication for tests
vi.mock('@/db/secure-db', () => ({
  requireAdmin: vi.fn().mockResolvedValue({
    id: 'test-admin',
    role: 'admin'
  })
}));

describe('Admin Metrics Endpoint', () => {
  it('returns metrics for authenticated admin', async () => {
    const response = await GET(mockRequest);
    expect(response.status).toBe(200);
  });

  it('returns 403 for non-admin', async () => {
    vi.mocked(requireAdmin).mockResolvedValueOnce(null);
    const response = await GET(mockRequest);
    expect(response.status).toBe(403);
  });
});

Design Resources

• Full design spec: docs/ADMIN-DEVELOPER-SUITE.md
• Design system: Use existing components from src/components/ui/
• Colors: Follow therapeutic palette (navy, teal, coral, cream)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: curiositech
• Source: curiositech/someclaude_skills
• License: MIT

Install and usage instructions live in the source repository linked above.