Cloudflare Workers Architecture

This document describes the two Cloudflare Workers deployments that make up the Adblock Compiler service, the differences between them, and how they relate to each other.

Overview

The Adblock Compiler is deployed as two separate Cloudflare Workers from a single GitHub repository. Each has a distinct role:

adblock-compiler-backend — The API Worker

What It Does

The backend worker is the compilation engine. It:

• Exposes a REST API (POST /compile, POST /compile/stream, POST /compile/batch, GET /metrics, etc.)
• Runs adblock/hostlist filter list compilation using the core src/ TypeScript logic (forked from AdguardTeam/HostlistCompiler)
• Handles async queue-based compilation via Cloudflare Queues
• Manages caching, rate limiting, and metrics via KV namespaces
• Stores compiled outputs in R2 and persists state in D1 + Durable Objects
• Runs scheduled background jobs (cache warming, health monitoring) via Cloudflare Workflows + Cron Triggers
• Also serves the compiled Angular frontend as static assets via its [assets] binding (bundled deployment mode)

Source

adblock-compiler/
├── worker/
│   └── worker.ts          ← entry point
├── src/                   ← core compiler logic (forked from AdGuard HostlistCompiler)
└── wrangler.toml          ← deployment configuration (name = "adblock-compiler-backend")

Key Bindings

adblock-compiler-frontend — The UI Worker

What It Does

The frontend worker is the Angular 21 SSR application. It:

• Server-side renders the Angular application at the Cloudflare edge using AngularAppEngine
• Serves the home page as a prerendered static page (SSG); all other routes are SSR per-request
• Serves JS/CSS/font bundles directly from Cloudflare's CDN via the ASSETS binding (the Worker never handles these requests)
• Calls the adblock-compiler-backend worker's REST API for all compilation operations

Source

adblock-compiler/
└── frontend/
    ├── src/               ← Angular 21 application source
    ├── server.ts          ← Cloudflare Workers fetch handler (AngularAppEngine)
    └── wrangler.toml      ← deployment configuration (name = "adblock-compiler-frontend")

Key Bindings

SSR Architecture

The server.ts fetch handler uses Angular 21's AngularAppEngine with the standard WinterCG fetch API — no Express, no Node.js HTTP server:

const angularApp = new AngularAppEngine();

export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        const response = await angularApp.handle(request);
        return response ?? new Response('Not found', { status: 404 });
    },
} satisfies ExportedHandler<Env>;

This means:

• Edge-compatible — runs in any WinterCG-compliant runtime (Cloudflare Workers, Deno Deploy, Fastly Compute)
• Fast cold starts — no Express middleware chain, no Node.js HTTP server initialisation
• Zero-overhead static assets — JS/CSS/fonts are served by Cloudflare CDN before the Worker is ever invoked

Relationship Between the Two Workers

Browser Request
      │
      ▼
┌─────────────────────────────────────────────┐
│         Cloudflare Edge Network             │
│                                             │
│  ┌──────────────────────────────────────┐   │
│  │  adblock-compiler-frontend           │   │
│  │  (Angular 21 SSR Worker)             │   │
│  │                                      │   │
│  │  • Prerendered home page (SSG)        │   │
│  │  • SSR for /compiler, /performance,  │   │
│  │    /admin, /api-docs, /validation    │   │
│  │  • Static assets served from CDN     │   │
│  │    via ASSETS binding (bypasses      │   │
│  │    Worker fetch handler entirely)    │   │
│  └───────────────┬──────────────────────┘   │
│                  │ API calls                │
│                  ▼                          │
│  ┌──────────────────────────────────────┐   │
│  │  adblock-compiler-backend            │   │
│  │  (TypeScript REST API Worker)        │   │
│  │                                      │   │
│  │  • POST /compile                     │   │
│  │  • POST /compile/stream (SSE)        │   │
│  │  • POST /compile/batch               │   │
│  │  • GET  /metrics                     │   │
│  │  • GET  /health                      │   │
│  │  • KV, R2, D1, Durable Objects,      │   │
│  │    Queues, Workflows, Hyperdrive      │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Two Deployment Modes

The backend worker supports two ways the frontend can be served:

1. Bundled Mode (single worker)

The root wrangler.toml includes an [assets] block pointing to the Angular build output:

[assets]
directory = "./frontend/dist/adblock-compiler/browser"
binding = "ASSETS"

This means a single wrangler deploy from the repo root deploys both the API and the Angular frontend as one unit. The Worker serves API requests; static assets are served by Cloudflare CDN via the binding.

2. Independent SSR Mode (two separate workers)

frontend/wrangler.toml deploys the Angular application as its own Worker with full SSR (AngularAppEngine). This is the adblock-compiler-frontend worker. It runs server-side rendering at the edge and calls the backend API for data.

Deployment

Backend

# From repo root
wrangler deploy

Frontend (Independent SSR mode)

cd frontend
npm run build    # ng build — compiles Angular + server.mjs
npm run deploy   # wrangler deploy

Local Development

# Backend API
wrangler dev                        # → http://localhost:8787

# Frontend (Angular dev server, CSR)
cd frontend && npm start            # → http://localhost:4200

# Frontend (Cloudflare Workers preview, mirrors production SSR)
cd frontend && npm run preview      # → http://localhost:8787

Renaming Note

These workers were renamed as of 2026-03-07.

Old name	New name
adblock-compiler	adblock-compiler-backend
adblock-compiler-angular-poc	adblock-compiler-frontend

| If you have existing workers under the old names in your Cloudflare dashboard, they will continue to run until manually deleted. The next wrangler deploy will create new workers under the updated names.

Further Reading

• worker/README.md — Worker API endpoints and implementation details
• frontend/README.md — Angular frontend architecture and Angular 21 features
• docs/deployment/cloudflare-pages.md — Cloudflare Pages deployment
• docs/cloudflare/README.md — Cloudflare-specific features index
• Cloudflare Workers Docs
• Wrangler CLI