Skip to content
Bloqr AI Bloqr AI

System Architecture

Switch to Zen 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 21 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 ────────────────────────────────────────────────────
    classDef client        fill:#1d6fbd,stroke:#0d4a8a,color:#fff
    classDef edge          fill:#6a1fa0,stroke:#4a1570,color:#fff
    classDef worker        fill:#b05a10,stroke:#7a3d08,color:#fff
    classDef corelib       fill:#b8860b,stroke:#8a6208,color:#fff
    classDef storage       fill:#2e7d32,stroke:#1a5421,color:#fff
    classDef observability fill:#c62828,stroke:#8e1c1c,color:#fff
    classDef auth          fill:#37474f,stroke:#1a2327,color:#fff
    classDef external      fill:#37474f,stroke:#1a2327,color:#fff

    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.