Bloqr™ Documentation

What is Bloqr?

Bloqr AI is a compiler-as-a-service for adblock and DNS filter lists. It ingests multiple sources, validates configuration with Zod, applies deterministic transformations, and ships edge-ready outputs from Cloudflare Workers.

Platform Snapshot

50+ Filter Sources

Multi-source ingestion across community and managed lists.

11 Transformations

Deterministic pipeline stages for cleanup, normalization, and optimization.

Zero-Copy Streaming

SSE and WebSocket delivery for live compile telemetry.

Edge-Native Runtime

Cloudflare Workers, Queues, D1, R2, and Workflows by default.

Start in Minutes

1. Open Quick Start and choose Docker, Deno, or Workers mode.
2. Validate your config with Zod Validation and Configuration.
3. Deploy to production with Deployment and Zero Trust Architecture.

Section Navigation

Getting Started

Overview Entry point for setup, migration, and practical guides.

Quick Start Launch Bloqr quickly using Docker, Deno, or Cloudflare Workers.

Client Libraries Implementation examples for API consumers.

Validation Errors Decode and resolve common schema validation failures.

API

API Overview REST API entrypoint and architectural context.

Quick Reference High-signal commands and endpoint recipes.

Streaming API SSE/WebSocket compile updates.

Zod Validation Trust-boundary validation and request contracts.

Cloudflare

Cloudflare Overview Platform-level integration map.

Services Overview Queues, Workflows, D1, R2, and analytics bindings.

Cloudflare Workflows Durable orchestration for long-running jobs.

Queue Diagnostics Operational visibility for queue throughput and failures.

Database

Database Setup Schema, local setup, and migration strategy.

Architecture Storage architecture and data domain boundaries.

Local Development Run Neon/Postgres-backed local workflows.

Prisma Schema Reference Canonical DB schema and modeling details.

Deployment

Deployment Overview All deployment paths and environment strategy.

Docker Containerized local and production deployment.

Workers Architecture Cloudflare-native runtime topology.

Production Readiness Checklist for secure and resilient rollouts.

Frontend

Frontend Overview SPA surface, architecture, and workflows.

Angular Frontend Angular 22 implementation details.

Validation UI User-facing validation and error visualization.

Vite Build and dev server pipeline for frontend delivery.

Security

Zero Trust Architecture Mandatory ZTA model across edge, worker, and UI layers.

ZTA Developer Guide Implementation guidance for secure handlers and flows.

API Shield Scanner Cloudflare API Shield vulnerability scanning controls.

Page Shield Integration Client-side security telemetry and protections.

Auth

Auth Overview Authentication and authorization architecture.

Auth Chain Reference Handler auth chain order and enforcement semantics.

API Authentication JWT/API key auth for API consumers.

Cloudflare Access Zero-trust access control for protected surfaces.

Admin

Admin Overview RBAC, audit, and operational controls.

Roles & Permissions Role matrix and delegated access model.

Admin API Reference Administrative API contracts and payloads.

Operator Guide Runbook for production administration.

Testing

Testing Overview Testing strategy and toolchain entrypoint.

Testing Guide Run and extend Deno/Vitest test suites.

E2E Testing End-to-end workflows and incident prevention.

Postman Testing Collections and environment validation flows.

Observability

Observability Overview Monitoring stack and telemetry conventions.

Sentry Integration Error tracking, tracing, and release visibility.

Cloudflare Native Observability Cloudflare-native metrics and diagnostics.

Prometheus Metrics Metrics export and dashboard integration.

Troubleshooting

Troubleshooting Overview Knowledge base and incident triage map.

KB-001: API Not Available Investigate and recover API availability incidents.

KB-002: Hyperdrive Database Down Database outage runbook and failover checks.

Neon Troubleshooting Neon operational diagnostics and remediation.

Tools

Ops Tools Overview Runbooks, diagnostic utilities, and local ops flows.

auth-healthcheck End-to-end auth diagnostics and failure localization.

Workflows CI/CD workflow architecture and automation.

Postman Workspace API testing collections and environment configuration.

Design system

All Bloqr visual standards — color tokens, typography, spacing, fonts, logos, and component primitives — are maintained in the standalone Bloqr-Systems/bloqr-design-system repository (@bloqr/design-system). It is the single source of truth for every Bloqr web property. Do not copy design assets or brand docs into this repo.

/frontend (Angular 22 + Material)

The Angular app consumes the design system at the CSS layer:

npm i @bloqr/design-system

In angular.json styles array (or styles.scss):

@import '@bloqr/design-system/styles.css';

Implement UI primitives (Button, Badge, Card, etc.) as Angular components against the same CSS custom properties the React primitives use — --orange-500, --bg-surface, --font-display, etc. The React source in components/ is the visual contract; it is not a runtime dependency for Angular.

Icons — done: Material Symbols has been fully replaced with self-hosted Lucide icons, 2 px stroke, rounded joins. <app-icon> (frontend/src/app/components/icon/icon.component.ts) renders inline SVG markup baked into icon-data.generated.ts at build time from the lucide-static devDependency — no lucide-angular runtime package, no icon font, no network request. See the design system README for the Material → Lucide name mapping. Any new Angular icon usage must go through <app-icon>, not a raw <svg>, <mat-icon>, or the lucide-angular package.

/docs

Link styles.css and use the token variables and guidelines/ specimen cards as the visual reference for all documentation pages.

Quick Paths by Role

Developer

Quick Start Bootstrap local development in minutes.

Usage: Configuration Compiler schema, defaults, and examples.

Development Architecture Core architecture and extension points.

Testing Guide Unit, integration, and E2E execution patterns.

Ops/Admin

Deployment Production deployment strategy and controls.

Admin System RBAC controls, plans, and audit capabilities.

Observability Tracing, metrics, and incident telemetry.

Troubleshooting Production KBs and remediation playbooks.

API Consumer

API Overview Endpoints, request schemas, and examples.

Streaming API Live compile status with SSE/WebSockets.

API Authentication JWT and API-key auth flows.

Client Libraries Integrate quickly from your app stack.

Architecture Overview

flowchart LR
    Client[Angular Frontend] --> Worker[Edge Worker]
    Worker --> Router[Hono Router]
    Router --> Queue[Cloudflare Queues]
    Router --> D1[(D1)]
    Router --> R2[(R2)]
    Queue --> Router

Bloqr Properties

Property	URL	Runtime	Notes
Landing	bloqr.dev	Marketing	Main product narrative and launch funnel.
App	app.bloqr.dev	Angular	Interactive compiler dashboard and admin UX.
API	api.bloqr.dev	Worker	OpenAPI portal and API base URL: https://api.bloqr.dev/api.
Docs	docs.bloqr.dev	Astro	Starlight documentation for developers and operators.

Contributing

Explore Guides Contributing Guide