BloqrCore
← Back to Documentation

Documentation

Bloqr Dashboard Guide

The Bloqr Dashboard is a unified .NET console application for managing ad-blocking filter compilation, configuration, and operations.

What is the Dashboard?

The Dashboard provides a menu-driven interface for:

  • Compiling filter rules from multiple sources with transformations and validation
  • Managing configurations with built-in wizard for generating compiler configs
  • Profile management for switching between different compilation configurations
  • Live progress monitoring with structured JSON logging and rollover
  • Config backups and corruption recovery with automatic versioning
  • Rules validation integrated throughout
  • Diagnostics for troubleshooting compilation issues

It's built on .NET 10 with a design that prioritizes resilience: errors never terminate the app, every exception is logged and displayed, and control always returns to the main menu.

Prerequisites

Requirement Version Notes
.NET SDK 10.0+ Cross-platform runtime
Deno 2.0+ Required by the underlying TypeScript rules compiler

Installation

Build from Source

From the repository root:

# Option 1: Using build script
./build.sh --dotnet       # Linux/macOS
./build.ps1 -DotNet       # Windows

# Option 2: Direct .NET build
cd src/apps/dashboard
dotnet restore BloqrDashboard.slnx
dotnet build BloqrDashboard.slnx

Run

cd src/apps/dashboard
dotnet run --project src/Bloqr.Dashboard.Console

Interactive Mode

The default mode shows the main menu with these options:

  • Compile Rules - Run a compilation with the active profile or specified config
  • Configuration - View and edit the active compiler configuration
  • Profiles - Create, switch, and manage named profiles
  • Logs - View structured compilation logs with filtering by app and time range
  • Diagnostics - Validate configs, check component status, and troubleshoot issues

Navigate the menu using arrow keys and Enter. The app never terminates on error — every exception is caught, logged, and the menu returns for the next action.

CLI Mode

Use the Dashboard from scripts or CI/CD pipelines:

# Show help
dotnet run --project src/Bloqr.Dashboard.Console -- --help

# Show version
dotnet run --project src/Bloqr.Dashboard.Console -- --version

# Compile using default profile
dotnet run --project src/Bloqr.Dashboard.Console -- --compile

# Compile using specific profile
dotnet run --project src/Bloqr.Dashboard.Console -- --profile production --compile

# Compile specific config file
dotnet run --project src/Bloqr.Dashboard.Console -- --compile /path/to/config.json

# Validate a config without compiling
dotnet run --project src/Bloqr.Dashboard.Console -- --validate-config /path/to/config.json

# List all profiles
dotnet run --project src/Bloqr.Dashboard.Console -- --list-profiles

# Activate a profile
dotnet run --project src/Bloqr.Dashboard.Console -- --activate-profile production

# Use a specific Dashboard config file
dotnet run --project src/Bloqr.Dashboard.Console -- --config ~/.config/bloqr-dashboard/custom-dashboard-config.jsonc --compile

# Set log level
dotnet run --project src/Bloqr.Dashboard.Console -- --log-level debug --compile

# Non-interactive mode (check status, no prompts)
dotnet run --project src/Bloqr.Dashboard.Console -- --non-interactive

# Force every source through a specific engine, and pick a browser-artifact path
dotnet run --project src/Bloqr.Dashboard.Console -- --compile --engine browser --browser-output ./output/rules.browser.txt

CLI Options Reference

Option Short Description
--help -h Show help message
--version -v Show version information
--config PATH Use a specific Dashboard configuration file
--profile NAME Activate a specific profile for this run
--log-level LEVEL Override log level (trace, debug, info, warn, error, silent)
--non-interactive Load config and exit without interactive prompts
--compile [PATH] Compile with optional config path
--validate-config PATH Validate a config without compiling
--list-profiles List all profiles
--activate-profile NAME Activate and persist a profile
--engine <auto|dns|browser> With --compile: force every source through this engine, bypassing per-source detection
--browser-output PATH With --compile: override the browser-syntax artifact's output path for a mixed-engine config

The Dashboard auto-detects redirected/piped stdin and switches to non-interactive mode automatically, so it's safe to invoke from scripts or CI without hanging.

Dual-Engine Compilation

--compile is dual-engine aware (epic #432): a configuration can mix DNS-engine and browser-engine sources, producing up to two output artifacts from one compile. IDashboardService.CompileAsync returns both when present, and the CLI output shows a Browser artifact: line alongside the usual result whenever one was produced. This flows through the interactive menus too:

  • Compile menu shows both artifacts (path, rule count, hash) when a mixed-engine compile ran, and prompts for an engine override before compiling.
  • Config wizard prompts for each source's engine (inferring one for a local file via a .NET port of EngineDetector, and asking directly for a remote URL) plus the configuration's defaultEngine.
  • Config editor round-trips engine/defaultEngine on an existing config without dropping them.
  • Diagnostics ("Validate a filter file") currently validates DNS/hosts syntax only — native browser-syntax validation in bloqr-validate is tracked separately and gates epic #432's closure.
  • Live progress shows two named child tasks ("DNS artifact"/"Browser artifact") under the compile root for a mixed-engine compile.

See Dual-Engine Compilation for how engine resolution works, and Configuration Reference for the engine/defaultEngine config fields.

Configuration

Dashboard Configuration File

The Dashboard stores its own settings in a .jsonc file, created automatically on first run:

  • Windows: %APPDATA%\bloqr-dashboard\dashboard-config.jsonc
  • Linux/macOS: $XDG_CONFIG_HOME/bloqr-dashboard/dashboard-config.jsonc (defaults to ~/.config/bloqr-dashboard/)

The file includes:

  • Log level and output settings
  • Profile management
  • Backup and recovery settings
  • Active profile tracking
  • AdGuard API configuration (if configured)

Environment Variables

Variable Description
BLOQR_DASHBOARD_CONFIG_DIR Override the entire Dashboard configuration directory
BLOQR_DASHBOARD_CONFIG Override just the config file path
BLOQR_DASHBOARD_LOG_LEVEL Override log level (trace, debug, info, warn, error, silent)

Compiler Configuration

The Dashboard compiles using compiler configuration files in JSON or JSONC format. See Configuration Reference for the complete schema.

Example compiler config:

{
  "name": "My Filter List",
  "description": "Custom ad-blocking filter",
  "version": "1.0.0",
  "sources": [
    {
      "name": "EasyList",
      "source": "https://easylist.to/easylist/easylist.txt",
      "type": "adblock",
      "transformations": ["Validate", "RemoveModifiers"]
    }
  ],
  "transformations": [
    "Deduplicate",
    "RemoveEmptyLines",
    "TrimLines",
    "InsertFinalNewLine"
  ]
}

Key Features

Configuration Wizard

Generate compiler configs interactively without hand-editing JSON:

  1. From the Dashboard menu, select Configuration
  2. Choose Generate New Configuration
  3. Answer prompts for sources, transformations, and output settings
  4. Review the generated JSON/JSONC before saving

Profile Management

Create named profiles to switch between different compilation setups:

# List profiles
dotnet run --project src/Bloqr.Dashboard.Console -- --list-profiles

# Activate a profile
dotnet run --project src/Bloqr.Dashboard.Console -- --activate-profile production

# Compile with a specific profile
dotnet run --project src/Bloqr.Dashboard.Console -- --profile production --compile

Each profile can have:

  • Its own compiler configuration
  • Custom log settings
  • Independent backup/recovery state

Backups and Recovery

The Dashboard automatically:

  • Creates backups when configurations change
  • Quarantines corrupt or invalid configs (dashboard-config.corrupt-<timestamp>.jsonc)
  • Recovers from the newest valid backup in interactive mode
  • Regenerates defaults if no backups exist

Structured Logging

Compilations produce JSON-formatted logs with:

  • Timestamp and severity (INFO, WARN, ERROR)
  • Event details (compilation start/end, transformations, errors)
  • Searchable via the Logs menu with filters by app and time range

Validation

Validate compiler configurations before compilation:

# Check a config without compiling
dotnet run --project src/Bloqr.Dashboard.Console -- --validate-config config.json

# Validation checks against the schema
# - Required fields present
# - Proper types and formats
# - Valid transformation names
# - Source accessibility

Diagnostics

The Diagnostics menu provides:

  • Configuration status and schema validation
  • Component health checks
  • Deno and compiler availability
  • Log file location and size
  • Backup status and recovery options

Embedding as a Library

The Dashboard can be embedded in other applications (e.g., a future .NET MAUI UI) by depending on:

  • Bloqr.Dashboard.Abstractions (interfaces, no dependencies)
  • Bloqr.Dashboard.Core (implementation)

The IDashboardService facade provides all compilation and profile operations without requiring the Spectre.Console terminal UI library:

var dashboardService = serviceProvider.GetRequiredService<IDashboardService>();
var result = await dashboardService.CompileAsync(configPath, profileName);

Troubleshooting

Dashboard won't start

Check prerequisites:

dotnet --version    # Should be 10.0+
deno --version      # Should be 2.0+

Configuration file corrupted

The Dashboard detects and automatically recovers corrupt configurations:

  1. The corrupt file is renamed to dashboard-config.corrupt-<timestamp>.jsonc
  2. Recovery uses the newest valid backup
  3. If no backups exist, defaults are regenerated

Compilation fails

  1. Use Diagnostics menu to check component status
  2. View Logs menu for detailed error messages
  3. Use --validate-config to check the compiler configuration
  4. Ensure sources are accessible and network is available

Logs not appearing

Check log level:

# Increase verbosity
dotnet run --project src/Bloqr.Dashboard.Console -- --log-level debug

View logs location in Diagnostics menu (logs are stored in:

  • Windows: %APPDATA%\bloqr-dashboard\logs\
  • Linux/macOS: ~/.config/bloqr-dashboard/logs/

Architecture & Design

For details on the Dashboard's architecture, project structure, and design patterns, see:

Next Steps

Note: The AdGuard DNS API client integration remains a separate, later issue. The Dashboard's API configuration extension points are wired but not connected to a real client yet.