Skip to content
Bloqr AI Bloqr AI™

System Architecture

Switch to normal mode

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.

flowchart TD
    %% ── Clients ──────────────────────────────────────────────────────────────
    Browser["Browser"]
    CLIUser["CLI User\n(Deno CLI)"]
    CICD["CI/CD Pipeline"]
    MCPAgent["AI Agent / MCP Client"]

    %% ── Edge / Zero Trust perimeter ─────────────────────────────────────────
    CFAccess["Cloudflare Access\n(Zero Trust / WAF)"]
    CFTurnstile["Cloudflare Turnstile\n(Human Verification)"]

    %% ── Angular Frontend (separate SSR Worker — bloqr-frontend) ──────
    subgraph FrontendWorker["bloqr-frontend  (separate SSR Worker)"]
        Frontend["Angular 22 SSR SPA\n(AngularAppEngine)"]
        FrontendAssets["ASSETS binding\n(JS/CSS/fonts — CDN)"]
        FrontendAPI["[[services]] API binding\n(wired in server.ts — routes /api/* internally)"]
    end

    %% ── Tail Worker (separate deployed service — bloqr-tail) ──────
    TailWorker["bloqr-tail\n(Tail Worker / Log Sink)"]

    %% ── Monolithic Worker ────────────────────────────────────────────────────
    subgraph MonolithWorker["bloqr-backend Worker  (worker/worker.ts)"]
        WorkerEntry["worker.ts\n(fetch · queue · scheduled · tail)"]
        HonoApp["hono-app.ts\n(Hono Router)"]
        Handlers["handlers/\ncompile · admin · auth · metrics\nqueue · websocket · proxy"]
        Workflows["workflows/\nCompilation · Batch\nCacheWarming · HealthMonitoring"]
        MCPAgentWorker["mcp-agent.ts\n(Playwright / CF Browser Run)"]
        BetterAuth["Better Auth\n(in-Worker · Neon / Hyperdrive)"]

        subgraph CoreLib["src/  (Core Library — inlined in monolith)"]
            Compiler["compiler/\nFilterCompiler · SourceCompiler\nIncrementalCompiler · WorkerCompiler"]
            Transformations["transformations/\n15+ strategies"]
            Downloader["downloader/\nFilterDownloader · PreprocessorEvaluator"]
            Config["configuration/\nZod schemas · ConfigurationValidator"]
            Storage["storage/\nIStorageAdapter\nD1 · Hyperdrive · Prisma adapters"]
            Services["services/\nFilterService · AnalyticsService\nPipelineService"]
            Queue["queue/\nIQueueProvider\nCloudflareQueueProvider"]
            Diagnostics["diagnostics/\nTracingContext · OTel exporter"]
            Formatters["formatters/\nadblock · hosts · dnsmasq · domains"]
            Diff["diff/  DiffReport"]
            Plugins["plugins/  PluginRegistry"]
            Utils["utils/\nCircuitBreaker · AsyncRetry · Logger"]
        end

        WorkerEntry --> HonoApp
        HonoApp --> Handlers
        HonoApp --> Workflows
        HonoApp --> MCPAgentWorker
        Handlers --> CoreLib
        Workflows --> CoreLib
    end

    %% ── Cloudflare Platform Bindings (key bindings — see wrangler.toml for full list) ──
    subgraph CFBindings["Cloudflare Platform Bindings (key — see wrangler.toml for full list)"]
        CFAssets["ASSETS binding\n(Angular SPA static files)"]
        KV_Cache["KV: COMPILATION_CACHE"]
        KV_RateLimit["KV: RATE_LIMIT"]
        KV_Metrics["KV: METRICS"]
        D1_DB["D1: DB\n(main database)"]
        D1_Admin["D1: ADMIN_DB"]
        R2_Filter["R2: FILTER_STORAGE"]
        R2_Logs["R2: COMPILER_LOGS"]
        CFQueues["Queues\nBLOQR_BACKEND_QUEUE\nBLOQR_BACKEND_QUEUE_HIGH_PRIORITY"]
        AnalyticsEngine["Analytics Engine\n(ANALYTICS_ENGINE · METRICS_PIPELINE)"]
        BrowserRendering["BROWSER\n(CF Browser Run)"]
        HyperdriveBinding["HYPERDRIVE\n(PostgreSQL connection pool)"]
        DOBindings["Durable Objects\nBLOQR_COMPILER_DO · MCP_AGENT"]
        WorkflowBindings["Workflow bindings\nCOMPILATION_WORKFLOW · BATCH_COMPILATION_WORKFLOW\nCACHE_WARMING_WORKFLOW · HEALTH_MONITORING_WORKFLOW"]
    end

    %% ── External Services ────────────────────────────────────────────────────
    subgraph ExternalServices["External Services"]
        Sentry["Sentry\n(Errors · Tracing)"]
        OTel["OpenTelemetry\n(Spans · Exporters)"]
        PostgreSQL["PostgreSQL\n(via Hyperdrive)"]
        FilterSources["Filter List Sources\n(EasyList · uBlock etc.)"]
    end

    %% ── Auth Stack ───────────────────────────────────────────────────────────
    LocalJWT["Local HS256 JWT\n(dev mode)"]
    APIKeys["API Keys\n(PostgreSQL / Hyperdrive)"]

    %% ── Connections ──────────────────────────────────────────────────────────
    Browser --> CFAccess
    MCPAgent --> CFAccess
    CICD --> CFAccess
    Browser --> CFTurnstile
    CFAccess --> FrontendWorker
    CFAccess --> MonolithWorker
    CFTurnstile --> MonolithWorker
    CLIUser --> CoreLib

    Frontend --> MonolithWorker
    FrontendAPI -->|"internal route\n(CF-Worker-Source: ssr)"| MonolithWorker

    MonolithWorker --> CFAssets
    MonolithWorker --> KV_Cache
    MonolithWorker --> KV_RateLimit
    MonolithWorker --> KV_Metrics
    MonolithWorker --> D1_DB
    MonolithWorker --> D1_Admin
    MonolithWorker --> R2_Filter
    MonolithWorker --> R2_Logs
    MonolithWorker --> CFQueues
    MonolithWorker --> AnalyticsEngine
    MonolithWorker --> BrowserRendering
    MonolithWorker --> HyperdriveBinding
    MonolithWorker --> DOBindings
    MonolithWorker --> WorkflowBindings

    MonolithWorker --> TailWorker
    MonolithWorker --> Sentry
    MonolithWorker --> OTel
    MonolithWorker --> FilterSources
    MonolithWorker --> LocalJWT
    MonolithWorker --> APIKeys

    HyperdriveBinding --> PostgreSQL

    TailWorker --> Sentry
    TailWorker --> OTel

    %% ── Class Definitions ────────────────────────────────────────────────────

    class Browser,CLIUser,CICD,MCPAgent client
    class CFAccess,CFTurnstile edge
    class Frontend,FrontendAssets,FrontendAPI,TailWorker worker
    class WorkerEntry,HonoApp,Handlers,Workflows,MCPAgentWorker worker
    class Compiler,Transformations,Downloader,Config,Services,Formatters,Diff,Plugins,Utils corelib
    class Storage,D1_DB,D1_Admin,KV_Cache,KV_RateLimit,KV_Metrics,CFQueues,CFAssets,R2_Filter,R2_Logs,HyperdriveBinding,PostgreSQL storage
    class DOBindings,WorkflowBindings storage
    class AnalyticsEngine,BrowserRendering,Sentry,OTel observability
    class BetterAuth,LocalJWT,APIKeys auth
    class FilterSources external

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.

Bloqr AI — The privacy you didn't know you needed.

© 2026 Bloqr AI™, a trademark of Bloqr Systems. Created by Bloqr Systems, founded by Jayson Knight.

Internet Hygiene (n.) — the ongoing practices that keep your digital life clean, private, and safe.

Get involved on GitHub

Our product repos live in the BloqrAI org, part of the Bloqr Systems GitHub Enterprise. Product repos are internal-visibility — enterprise membership is required to view them.