AdBlock Compiler Documentation

Welcome to the AdBlock Compiler documentation. This directory contains all the detailed documentation for the project.

Quick Links

• Main README - Project overview and quick start
• CHANGELOG - Version history and release notes

Documentation Structure

docs/
├── api/             # REST API reference, OpenAPI spec, streaming, and validation
├── cloudflare/      # Cloudflare-specific features (Queues, D1, Workflows, Analytics)
├── database-setup/  # Database architecture, PostgreSQL, Prisma, and local dev setup
├── deployment/      # Docker, Cloudflare Pages/Containers, and production readiness
├── development/     # Architecture, extensibility, diagnostics, and code quality
├── frontend/        # Angular SPA, Vite, Tailwind CSS, and UI components
├── guides/          # Getting started, migration, client libraries, and troubleshooting
├── postman/         # Postman collection and environment files
├── reference/       # Version management, environment config, and project reference
├── releases/        # Release notes and announcements
├── testing/         # Testing guides, E2E, and Postman API testing
└── workflows/       # GitHub Actions CI/CD workflows and automation

Getting Started

• Quick Start Guide - Get up and running with Docker in minutes
• API Documentation - REST API reference and examples
• Client Libraries - Client examples for Python, TypeScript, and Go
• Migration Guide - Migrating from @adguard/hostlist-compiler
• Troubleshooting - Common issues and solutions

Usage

• Configuration - Configuration schema reference and examples
• Transformations - All 11 available transformations with examples

API Reference

• API Documentation - REST API reference
• API Quick Reference - Common commands and workflows
• OpenAPI Support - OpenAPI 3.0 specification details
• OpenAPI Tooling - API specification validation and testing
• Streaming API - Real-time event streaming via SSE and WebSocket
• Batch API Guide - 📊 Comprehensive guide with diagrams
• Zod Validation Guide - Runtime validation with Zod schemas
• AGTree Integration - AST-based adblock rule parsing with @adguard/agtree
• Platform Support - Edge runtimes, Cloudflare Workers, browsers, and custom fetchers

Cloudflare Worker

• Cloudflare Overview - Cloudflare-specific features index
• Worker Overview - Worker implementation and API endpoints
• Admin Dashboard - Real-time metrics, queue monitoring, and system health
• Queue Support - Async compilation via Cloudflare Queues
• Queue Diagnostics - Diagnostic events for queue-based compilation
• Cloudflare Workflows - Durable execution for long-running compilations
• Workflow Diagrams - System architecture and flow diagrams
• Cloudflare Analytics Engine - High-cardinality metrics and telemetry
• Tail Worker - Observability and logging
• Tail Worker Quick Start - Get tail worker running in 5 minutes
• Worker E2E Tests - Automated end-to-end test suite

Deployment

• Docker - Docker Compose deployment guide with Kubernetes examples
• Cloudflare Containers - Deploy to Cloudflare edge network
• Cloudflare Pages - Deploy to Cloudflare Pages
• Cloudflare Workers Architecture - Backend vs frontend workers, deployment modes, and their relationship
• Deployment Versioning - Automated deployment tracking and versioning
• Production Readiness - Production readiness assessment and recommendations

Storage & Database

• Storage Module - Prisma-based storage with SQLite default
• Prisma Backend - SQL/NoSQL database support
• Database Architecture - Database schema and design
• Database Evaluation - PlanetScale vs Neon vs Cloudflare vs Prisma comparison
• Prisma Evaluation - Storage backend comparison
• Cloudflare D1 - Edge database integration
• Local Development Setup - Local PostgreSQL dev environment

Frontend Development

• Frontend Overview - Frontend documentation index
• Angular Frontend - Angular 21 SPA with Material Design 3 and SSR
• SPA Benefits Analysis - Analysis of SPA benefits and migration recommendations
• Vite Integration - Frontend build pipeline with HMR, multi-page app, and React/Vue support
• Tailwind CSS - Utility-first CSS framework integration with PostCSS
• Validation UI - Color-coded validation error UI component

Development

• Development Overview - Development documentation index
• Architecture - System architecture and design decisions
• Extensibility - Custom transformations and extensions
• Circuit Breaker - Fault-tolerant source downloads with automatic recovery
• Diagnostics - Event emission and tracing
• Benchmarks - Performance benchmarking guide
• Code Review - Code quality review and recommendations
• Structured Logging & OpenTelemetry - Structured JSON logs, per-module levels, and distributed tracing
• Error Reporting - Centralized error tracking with Sentry and Cloudflare Analytics Engine

Testing

• Testing Guide - How to run and write tests
• E2E Testing - End-to-end integration testing dashboard
• Worker E2E Tests - Cloudflare Worker automated end-to-end tests
• Postman Testing - Import and test with Postman collections

CI/CD & Workflows

• GitHub Actions Workflows - CI/CD workflow documentation and best practices
• Workflow Improvements - Summary of workflow parallelization improvements
• GitHub Actions Environment Setup - Layered environment configuration for CI
• Workflow Cleanup Summary - Summary of workflow consolidation changes
• Workflows Reference - Detailed CI/CD workflow reference

Reference

• Reference Overview - Reference documentation index
• Version Management - Version synchronization details
• Auto Version Bump - Automatic versioning via Conventional Commits
• Environment Configuration - Environment variables and layered config system
• Validation Errors - Understanding validation errors and reporting
• Bugs and Features - Known bugs and feature requests
• GitHub Issue Templates - Ready-to-use GitHub issue templates
• AI Assistant Guide - Context for AI assistants working with this codebase

Releases

• Release 0.8.0 - v0.8.0 release notes
• Blog Post - Project overview and announcement

Contributing

See the main README and CONTRIBUTING for information on how to contribute to this project.