System Architecture
Current monolithic architecture and target decomposed service architecture for bloqr-backend.
This document describes the current (monolithic) architecture of the bloqr-backend service and the target architecture after the monolith is decomposed into discrete, independently deployable packages and services.
Summary
The current system is a monolith: every concern — compilation, transformation, storage, queuing, diagnostics, plugins, and formatters — lives inside a single Cloudflare Worker alongside its Hono router and request handlers. The Angular SSR frontend is deployed as its own separate Worker (bloqr-frontend) using AngularAppEngine; the [[services]] binding to the backend is wired in server.ts, routing SSR-time /api/* calls to the backend over the internal Cloudflare network with a CF-Worker-Source: ssr header. Cloudflare Access and Turnstile form the Zero Trust perimeter before any request reaches either Worker. External services (Sentry, OpenTelemetry, PostgreSQL, and filter-list sources) are consumed directly from within the single backend process. Authentication is handled by Better Auth, which runs entirely within the Worker backed by Neon PostgreSQL via Cloudflare Hyperdrive. A dedicated bloqr-tail Worker (configured via [[tail_consumers]]) acts as the log sink, forwarding structured logs to Sentry and OTel. This coupling makes it difficult to evolve, version, or deploy individual capabilities independently.
Summary
The target architecture decomposes the monolith into independently deployable units. The four core concerns — compilation/transformations, storage adapters, queue abstractions, and diagnostics/tracing — are extracted into dedicated JSR packages (@bloqr/compiler, @bloqr-systems/bloqr-storage, @bloqr-systems/bloqr-queue, @bloqr-systems/bloqr-diagnostics) that can be versioned and published independently. The Cloudflare Worker becomes a thin routing layer (bloqr-backend-api) that imports these packages as dependencies and delegates to two separate Worker service bindings: bloqr-backend-workflows for Durable Workflows and bloqr-backend-mcp for the Playwright MCP agent. The Angular SSR frontend continues to be served via the Worker ASSETS binding (not as a standalone Cloudflare Pages project), using the Hono RPC client (hc<AppType>()) for fully type-safe API calls. The Deno CLI becomes its own standalone binary that depends only on the core library. The Zero Trust perimeter (Cloudflare Access + Turnstile), platform bindings, and external services remain unchanged — only the internal structure is simplified. Better Auth replaces Clerk and runs entirely within the Worker backed by Neon PostgreSQL via Cloudflare Hyperdrive.
Migration status
The monolith is currently in code freeze at v0.79.4 for e2e testing and refactoring. The target architecture is the decomposition goal for the next major milestone.