Admin Dashboard (happy-admin)
Relevant source files
The following files were used as context for generating this wiki page:
The Admin Dashboard (happy-admin) is a specialized internal tool within the Happy ecosystem designed to visualize sync metrics and manage administrative tasks. It consists of a Vue.js 3 Single Page Application (SPA) frontend and a dedicated Hono-based API backend. The system provides real-time insights into Cloudflare Analytics Engine datasets, bundle size trends, and WebSocket performance.
The dashboard serves as the primary interface for administrators to monitor the health of the synchronization engine used by the mobile and CLI clients. It enforces strict security through "admin-only" role-based access control, CSRF protection, and rate limiting on sensitive endpoints.
Sources: apps/admin/web/CLAUDE.md:8-12, apps/admin/api/CLAUDE.md:8-12, apps/admin/api/src/index.ts:101-105
System Architecture
The Admin Dashboard architecture is split into two distinct projects that communicate over HTTPS. The frontend is a static SPA served via Cloudflare Workers (using the [site] bucket), while the backend is a Hono API running on Cloudflare Workers edge functions.
This diagram illustrates the flow where the Dashboard frontend interacts with the API, which in turn queries both the main application database and the Analytics Engine datasets populated by the primary server workers.
Sources: apps/admin/api/CLAUDE.md:16-30, apps/admin/web/CLAUDE.md:43-51
Frontend Components (happy-admin)
The frontend is built with Vue.js 3 using the Composition API and Tailwind CSS. It is organized into views and reusable components that consume specialized composables for data fetching.
Core Technology Stack
| Technology | Purpose |
|---|---|
| Vue.js 3 | Frontend framework (Composition API) |
| Vite | Build tool and dev server |
| Tailwind CSS | Utility-first styling |
| Better-Auth | Client-side session management |
| TanStack Table/Charts | Data visualization and metrics display |
Sources: apps/admin/web/CLAUDE.md:14-25
Dashboard Features
The main Dashboard.vue view integrates several specialized metric sections:
- Metrics Summary: Displays total syncs, average duration, cache hit rates, and success rates.
- Sync Activity Charts: Visualizes sync counts and durations over time using time-bucketed data.
- Bundle Size Metrics: Monitors latest bundle sizes and 30-day trends across different platforms (iOS, Android, Web).
- Validation Metrics: Tracks schema validation failures and identifies unknown data types.
- WebSocket Performance: Measures connection times and broadcast latency.
Sources: apps/admin/web/src/app/views/Dashboard.vue:15-32, apps/admin/web/src/i18n/locales/en.ts:60-80
API Backend (happy-admin-api)
The backend is a Hono-based API that acts as a secure gateway to the Analytics Engine and the administrative tables in the D1 database.
API Endpoint Categories
| Path | Auth Requirement | Description |
|---|---|---|
/api/auth/* | Public/Session | Handles sign-in, sign-out, and session verification via Better-Auth. |
/api/metrics/* | Admin Role | Queries Analytics Engine for sync, bundle, and WebSocket metrics. |
/api/admin/* | Admin Role | User management, role updates, and audit log access. |
/api/docs | Public | Interactive Swagger UI documentation. |
Sources: apps/admin/api/CLAUDE.md:124-155, apps/admin/api/src/index.ts:110-120
Security Implementation
The API implements multiple layers of security to protect sensitive metrics and administrative functions:
- CSRF Protection: Implements a double-submit cookie pattern requiring an
X-CSRF-Tokenheader for all state-changing requests (POST, PUT, DELETE). - Rate Limiting: Enforces strict limits on authentication (e.g., 5 req/min for sign-in) and metrics (60 req/min) to prevent brute force and resource abuse.
- Role-Based Access (RBAC): Every protected request is intercepted by
adminAuthMiddlewarewhich verifies the user has theadminrole in the database. - Security Headers: Includes CSP, X-Frame-Options, and HSTS to harden the browser environment.
Sources: apps/admin/api/src/index.ts:54-105, apps/admin/api/CLAUDE.md:130-142
Data Models and Analytics
The dashboard consumes data from two primary sources: the Cloudflare Analytics Engine (AE) for high-volume event data and D1 for persistent relational data.
Analytics Engine Schema
The AE integration queries the sync_metrics_dev and sync_metrics_prod datasets.
| AE Field | Mapping | Description |
|---|---|---|
blob1 | Sync Type | Entity being synced (e.g., session, machine). |
blob2 | Sync Mode | Mode of sync: full, incremental, or cached. |
blob3 | Cache Status | Indicates a hit or miss. |
double1 | Duration | Sync duration in milliseconds. |
double2 | Success | Success flag (1 for success, 0 for failure). |
Sources: apps/admin/web/CLAUDE.md:160-168, apps/admin/web/src/app/views/Dashboard.vue:350-370
Relational Database (D1)
The D1 database stores user accounts and audit logs. A daily cron trigger (running at 03:00 UTC) performs cleanup of admin_audit_logs older than 90 days.
Development and Deployment
Commands and Workflow
# Frontend
yarn build:app # Build the Vue SPA
yarn deploy:prod # Deploy to Cloudflare Workers
# Backend
yarn db:migrate # Apply Better-Auth migrations to D1
yarn deploy:prod # Deploy Hono API to Cloudflare
Sources: apps/admin/web/CLAUDE.md:65-75, apps/admin/api/CLAUDE.md:73-85
Environment Configuration
The system requires specific secrets to be set in the Cloudflare environment:
ANALYTICS_ACCOUNT_ID: Cloudflare account ID for AE access.ANALYTICS_API_TOKEN: Token with Analytics Read permissions.BETTER_AUTH_SECRET: Secret used for signing session tokens.
Sources: apps/admin/api/CLAUDE.md:214-230, apps/admin/web/CLAUDE.md:132-140
Conclusion
The Admin Dashboard (happy-admin) provides a critical observability layer for the Happy ecosystem. By leveraging Cloudflare's edge compute and Analytics Engine, it delivers high-performance metrics visualization without the overhead of traditional server infrastructure. Its security-first design ensures that administrative capabilities and system telemetry remain restricted to authorized personnel.
Sources: apps/admin/api/CLAUDE.md:8-12, apps/admin/web/CLAUDE.md:8-12