Admin System

The bloqr-backend admin system is a 10-panel Angular Material dashboard backed by a Cloudflare Worker API. It provides granular, role-based control over every runtime aspect of the platform — tiers, scopes, feature flags, endpoint overrides, announcements, and user management — without redeploying.

Architecture

Two admin surfaces, two hosts

Bloqr separates administration into two surfaces on two hosts so the more powerful one is fenced off:

The operator surface is served by the dedicated bloqr-admin Worker — a thin gateway that operator-gates requests at the edge and forwards them to this same admin API over a service binding. See bloqr-admin Worker.

Key Design Decisions

Dedicated ADMIN_DB for blast-radius isolation

The admin system uses its own D1 database (ADMIN_DB) rather than sharing the application's DB binding. This ensures:

• Schema isolation — Admin migrations live in admin-migrations/ and cannot interfere with application tables.
• Blast-radius containment — A bad admin migration or runaway query cannot corrupt application data.
• Independent scaling — Admin traffic patterns (low volume, write-heavy) are separated from application traffic (high volume, read-heavy).

KV write-through caching

Role resolution is the hottest path in the admin system — every authenticated request evaluates it. Results are cached in the RATE_LIMIT KV namespace with a 5-minute TTL and admin:role:{clerkUserId} key pattern. Cache entries are invalidated on role assignment or revocation.

Clerk identity + D1 policy for role management

Authentication and identity live in Clerk. Authorization policy lives in D1. The split works like this:

1. Clerk JWT proves who you are (identity, publicMetadata.role === 'admin' gate).
2. ADMIN_DB determines what you can do (role → permissions mapping).
3. KV cache makes it fast at the edge.

This avoids coupling Clerk's metadata model to fine-grained permission logic while keeping the auth flow simple.

Documentation

Related Documentation

• Admin Access (Auth) — Legacy ADMIN_KEY → Clerk migration path
• Zero Trust Architecture — Security model the admin system implements
• Cloudflare D1 — D1 database fundamentals