Admin Dashboard API
Relevant source files
The following files were used as context for generating this wiki page:
The Admin Dashboard API (internally named happy-admin-api) is a specialized backend service designed to support the Happy Admin dashboard. It serves as the bridge between the Vue.js frontend dashboard and the core Happy ecosystem's data, specifically handling authentication via Better-Auth and performance metrics via Cloudflare Analytics Engine.
The API is built using the Hono framework with OpenAPI 3.1 support and runs on Cloudflare Workers. It provides a secure, zero-trust interface for administrators to monitor synchronization performance, bundle sizes, and system health across the production and development environments.
Sources: apps/admin/api/CLAUDE.md:1-10, apps/admin/api/src/index.ts:15-30
Architecture and Infrastructure
The Admin Dashboard API is an API-only component that interacts with several Cloudflare services and the shared Happy D1 database.
System Components
- Framework: Hono v4+ with
@hono/zod-openapifor type-safe routing and documentation. - Runtime: Cloudflare Workers (Edge).
- Database: Shared D1 (SQLite) instance used by the main Happy ecosystem, containing
Better-Authtables. - Metrics Storage: Cloudflare Analytics Engine (SQL API) for sync and performance data.
- Authentication: Better-Auth with a D1 adapter.
Sources: apps/admin/api/CLAUDE.md:38-48, apps/admin/api/src/index.ts:32-45
Data Flow Diagram
The following diagram illustrates how the Admin Dashboard API communicates with the frontend and infrastructure.
The dashboard communicates via CORS and cross-origin cookies to the API, which then interacts with the Analytics Engine for metrics and D1 for authentication data.
Sources: apps/admin/api/CLAUDE.md:15-33, apps/admin/api/src/index.ts:57-78
Security and Middleware
The API implements a robust security stack to protect administrative data and prevent unauthorized access.
Security Stack
| Feature | Implementation | Description |
|---|---|---|
| CORS | Environment-aware | Allows requests from localhost in dev and specific enflamemedia.com subdomains in prod. |
| CSRF | Double-submit cookie | Requires X-CSRF-Token header for state-changing requests (POST, PUT, DELETE). |
| Rate Limiting | KV-based | Prevents brute force on auth (5/min) and Analytics Engine abuse (60/min). |
| Body Limits | Middleware | Enforces a 1MB payload limit for the Admin API to prevent DoS. |
| Authorization | adminAuthMiddleware | Validates session and ensures the user has role = 'admin' in the database. |
| Sources: apps/admin/api/src/index.ts:57-110, apps/admin/api/CLAUDE.md:118-135 |
Authentication Flow
Better-Auth handles the identity management. Public registration is disabled; new admins must be created via direct database insertion or the internal Admin API by an existing administrator.
Sources: apps/admin/api/CLAUDE.md:115-120, apps/admin/api/src/index.ts:133-145
API Endpoints
The API is divided into public authentication routes and protected administrative/metrics routes.
Authentication Routes (/api/auth/*)
These endpoints manage user sessions and are protected by rate limiting.
POST /api/auth/sign-in/email: Login with credentials.POST /api/auth/sign-out: Terminate the current session.GET /api/auth/session: Retrieve the current user's session data.GET /api/auth/reference: OpenAPI documentation for authentication.
Sources: apps/admin/api/CLAUDE.md:137-145, apps/admin/api/src/index.ts:130-135
Metrics API (/api/metrics/*)
Requires both a valid session and the admin role. These endpoints query the Cloudflare Analytics Engine.
| Endpoint | Method | Description |
|---|---|---|
/summary | GET | 24h aggregated sync metrics (type, mode, duration). |
/timeseries | GET | Time-bucketed metrics for chart visualization. |
/cache-hits | GET | Profile cache hit rate statistics. |
/bundle-trends | GET | CI/CD bundle size trends for mobile/web. |
/websocket/summary | GET | WebSocket connection and broadcast latency stats. |
| Sources: apps/admin/api/CLAUDE.md:155-170, apps/admin/web/src/app/lib/api.ts:168-240 |
Admin Management (/api/admin/*)
Used for internal dashboard management tasks, such as user role updates and audit logging.
Sources: apps/admin/api/src/index.ts:153-157
Data Models and Schemas
The API primarily returns structured JSON data derived from Analytics Engine SQL queries.
Metrics Summary Object
{
"syncType": "string",
"syncMode": "string",
"count": 120,
"avgDurationMs": 45.5,
"p95DurationMs": 120.0,
"successRate": 0.99
}
Sources: apps/admin/web/src/app/lib/api.ts:50-57
Audit Log Retention
The API includes an automated cleanup task for admin_audit_logs.
- Policy: Logs older than 90 days are deleted.
- Execution: Daily at 03:00 UTC via Cloudflare Cron Trigger.
- Source:
cleanupExpiredAuditLogsfunction called within thescheduledworker handler.
Sources: apps/admin/api/CLAUDE.md:214-235, apps/admin/api/src/index.ts:255-275
Documentation and Health Monitoring
The API provides self-documenting features and comprehensive health checks.
Readiness Probes
The /ready endpoint performs a multi-dependency check:
- Database: Validates D1 connectivity with a
SELECT 1query. - Analytics Bindings: Ensures
ANALYTICS_ACCOUNT_IDandANALYTICS_API_TOKENexist. - Analytics Secrets: Verifies the Secrets Store can actually retrieve the tokens (HAP-638).
Sources: apps/admin/api/src/index.ts:182-225
OpenAPI Documentation
The API serves its own specification and a Swagger UI:
- Spec:
GET /api/openapi.json(OpenAPI 3.1.0) - UI:
GET /api/docs(via@hono/swagger-ui)
Sources: apps/admin/api/src/index.ts:227-245, apps/admin/web/CLAUDE.md:162-167
Conclusion
The Admin Dashboard API provides a secure, specialized backend for system oversight. By leveraging Cloudflare's edge capabilities and the Analytics Engine, it provides real-time visibility into the Happy ecosystem's performance while maintaining strict security through Better-Auth and multi-layered middleware.
Sources: apps/admin/api/src/index.ts:15-50, apps/admin/web/src/app/views/Dashboard.vue:1-30