SPEC.md

Admin Dashboard Specification

Overview

A modern admin dashboard built with:

• Edge-first architecture using Cloudflare Workers
• Neon Serverless Postgres for database
• Clerk for authentication
• Drizzle ORM for type-safe database operations
• Hono for API routing
• React + Vite for frontend

Current Status

Completed

• Project structure setup
• Database schema design
• Neon + Drizzle integration
• Basic user model implementation
• Clerk webhook integration
• Health check endpoint
• Type-safe schema validation with Zod
• User metadata storage
• Transaction-free database operations for Neon HTTP
• Structured logging implementation
• Webhook payload validation
• User lifecycle event handling (create/update/delete)

In Progress

• Frontend implementation
• User management UI
• Role-based access control
• API documentation
• E2E testing setup

Architecture

Backend (Cloudflare Worker)

API Routes

• /api/health - Health check endpoint
• /api/webhooks/clerk - Clerk webhook endpoint for user sync

Database Schema

Currently implemented tables:

• users - Stores user information synced from Clerk
  • Basic fields: id, clerkId, email, firstName, lastName
  • Timestamps: createdAt, updatedAt
• user_data - Stores user metadata
  • Flexible key-value storage
  • Used for signup tracking and name history

Authentication & User Management

• Clerk handles user authentication
• Webhook integration for user sync:
  • User creation with metadata
  • User updates with change tracking
  • User deletion with cleanup
• All database operations are transaction-free for Neon HTTP compatibility

Frontend (React + Vite)

• To be implemented
• Will use React Query for data fetching
• Material UI for components
• Type-safe API client

Development Setup

1. Environment Variables:

# Neon Database
NEON_DATABASE_URL=

# Clerk
CLERK_SECRET_KEY=
CLERK_WEBHOOK_SECRET=

# Cloudflare
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_ACCOUNT_ID=

2. Development Commands:

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run database migrations
pnpm db:migrate

Next Steps

1. Implement user search and filtering
2. Add user profile management
3. Set up frontend project structure
4. Implement role-based access control
5. Add API documentation
6. Set up testing infrastructure