Skip to content

fix: Mermaid diagram errors, dark theme compatibility, and mdhelp scroll reset #1540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jaypatrick merged 7 commits into from
Apr 13, 2026
Merged

fix: Mermaid diagram errors, dark theme compatibility, and mdhelp scroll reset #1540

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
78dfbf5
Initial plan
Copilot Apr 12, 2026
72ff503
Merge branch 'main' into copilot/fix-mermaid-diagram-errors
jaypatrick Apr 12, 2026
0caee0a
fix: fix Mermaid diagram errors, dark theme compat, and mdhelp scroll…
Copilot Apr 12, 2026
76b1975
fix: use withInMemoryScrolling instead of withRouterConfig for scroll…
Copilot Apr 12, 2026
b8d9fa5
fix: apply review feedback — scrollOffset, queryParamMap.get for URL …
Copilot Apr 13, 2026
d20d0e4
fix: move scrollOffset to withRouterConfig — not valid in InMemoryScr…
Copilot Apr 13, 2026
7c18973
fix: implement scrollOffset via ViewportScroller.setOffset — not a ro…
Copilot Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 43 additions & 43 deletions docs/architecture/SYSTEM_ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,18 @@ This document describes the current (monolithic) architecture of the adblock-com
```mermaid
flowchart TD
%% ── Clients ──────────────────────────────────────────────────────────────
Browser["🌐 Browser"]
CLIUser["💻 CLI User\n(Deno CLI)"]
CICD["⚙️ CI/CD Pipeline"]
MCPAgent["🤖 AI Agent / MCP Client"]
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)"]
CFAccess["Cloudflare Access\n(Zero Trust / WAF)"]
CFTurnstile["Cloudflare Turnstile\n(Human Verification)"]

%% ── Angular Frontend (separate SSR Worker — adblock-frontend) ──────
subgraph FrontendWorker["adblock-frontend (separate SSR Worker)"]
Frontend["📱 Angular 21 SSR SPA\n(AngularAppEngine)"]
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
Expand All @@ -35,7 +35,7 @@ flowchart TD
Handlers["handlers/\ncompile · admin · auth · metrics\nqueue · websocket · proxy"]
Workflows["workflows/\nCompilation · Batch\nCacheWarming · HealthMonitoring"]
MCPAgentWorker["mcp-agent.ts\n(Playwright / CF Browser Rendering)"]
BetterAuth["🔐 Better Auth\n(in-Worker · Neon / Hyperdrive)"]
BetterAuth["Better Auth\n(in-Worker · Neon / Hyperdrive)"]

subgraph CoreLib["src/ (Core Library — inlined in monolith)"]
Compiler["compiler/\nFilterCompiler · SourceCompiler\nIncrementalCompiler · WorkerCompiler"]
Expand Down Expand Up @@ -80,15 +80,15 @@ flowchart TD

%% ── 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.)"]
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)"]
LocalJWT["Local HS256 JWT\n(dev mode)"]
APIKeys["API Keys\n(PostgreSQL / Hyperdrive)"]

%% ── Connections ──────────────────────────────────────────────────────────
Browser --> CFAccess
Expand Down Expand Up @@ -131,14 +131,14 @@ flowchart TD
TailWorker --> OTel

%% ── Class Definitions ────────────────────────────────────────────────────
classDef client fill:#4A90D9,stroke:#2C5F8A,color:#fff
classDef edge fill:#7B68EE,stroke:#4B3FA0,color:#fff
classDef worker fill:#E8A838,stroke:#B07820,color:#fff
classDef corelib fill:#F0C040,stroke:#C09010,color:#333
classDef storage fill:#5BA85A,stroke:#3A7039,color:#fff
classDef observability fill:#D9534F,stroke:#A02B28,color:#fff
classDef auth fill:#9B59B6,stroke:#6C3483,color:#fff
classDef external fill:#7F8C8D,stroke:#555F60,color:#fff
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
Expand All @@ -163,14 +163,14 @@ The current system is a **monolith**: every concern — compilation, transformat
```mermaid
flowchart TD
%% ── Clients ──────────────────────────────────────────────────────────────
Browser["🌐 Browser"]
CLIUser["💻 CLI User\n(Deno CLI)"]
CICD["⚙️ CI/CD Pipeline"]
MCPAgent["🤖 AI Agent / MCP Client"]
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)"]
CFAccess["Cloudflare Access\n(Zero Trust / WAF)"]
CFTurnstile["Cloudflare Turnstile\n(Human Verification)"]

%% ── Angular Frontend (served via API Worker STATIC_ASSETS binding) ─────────────
subgraph FrontendApp["adblock-frontend (Worker STATIC_ASSETS binding)"]
Expand All @@ -186,7 +186,7 @@ flowchart TD
subgraph APIWorker["adblock-compiler-api (Cloudflare Worker — thin routing layer)"]
HonoRouter["hono-app.ts\n(OpenAPIHono Router)"]
APIHandlers["handlers/\ncompile · admin · auth\nmetrics · queue · websocket"]
BetterAuth["🔐 Better Auth\n(in-Worker · Neon / Hyperdrive)"]
BetterAuth["Better Auth\n(in-Worker · Neon / Hyperdrive)"]
end

%% ── Worker Service Bindings ──────────────────────────────────────────────
Expand Down Expand Up @@ -222,15 +222,15 @@ flowchart TD

%% ── 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.)"]
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)"]
LocalJWT["Local HS256 JWT\n(dev mode)"]
APIKeys["API Keys\n(PostgreSQL / Hyperdrive)"]

%% ── Connections ──────────────────────────────────────────────────────────
Browser --> CFAccess
Expand Down Expand Up @@ -282,14 +282,14 @@ flowchart TD
APIWorker --> FilterSources

%% ── Class Definitions ────────────────────────────────────────────────────
classDef client fill:#4A90D9,stroke:#2C5F8A,color:#fff
classDef edge fill:#7B68EE,stroke:#4B3FA0,color:#fff
classDef worker fill:#E8A838,stroke:#B07820,color:#fff
classDef jsrpkg fill:#F0C040,stroke:#C09010,color:#333
classDef storage fill:#5BA85A,stroke:#3A7039,color:#fff
classDef observability fill:#D9534F,stroke:#A02B28,color:#fff
classDef auth fill:#9B59B6,stroke:#6C3483,color:#fff
classDef external fill:#7F8C8D,stroke:#555F60,color:#fff
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 jsrpkg 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
Expand Down
36 changes: 18 additions & 18 deletions docs/auth/auth-chain-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,32 +51,32 @@ flowchart TD
APIKEY --> HASH["SHA-256 hash token"]
HASH --> LOOKUP["Query api_keys table<br/>via Hyperdrive"]
LOOKUP -->|"Found + valid"| TIER["Resolve owner tier<br/>from users table"]
TIER --> AUTH_OK["✅ Authenticated<br/>(api-key method)"]
LOOKUP -->|"Not found / expired / revoked"| REJECT["❌ 401 Rejected"]
TIER --> AUTH_OK["Authenticated<br/>(api-key method)"]
LOOKUP -->|"Not found / expired / revoked"| REJECT["401 Rejected"]

BA -->|"Valid session<br/>(cookie or bearer)"| ZTA["Run Token Validators<br/>(ZTA checks)"]
ZTA -->|"Pass"| BA_OK["✅ Authenticated<br/>(better-auth method)"]
ZTA -->|"Fail"| REJECT2["❌ 401 Rejected"]
ZTA -->|"Pass"| BA_OK["Authenticated<br/>(better-auth method)"]
ZTA -->|"Fail"| REJECT2["401 Rejected"]

BA -->|"No credentials<br/>(no error)"| CLERK_CHECK{"Clerk fallback<br/>enabled?"}
BA -->|"Error<br/>(bad token)"| REJECT3["❌ 401 Rejected"]
BA -->|"Error<br/>(bad token)"| REJECT3["401 Rejected"]

CLERK_CHECK -->|"Yes + JWT token"| CLERK["Clerk JWT<br/>(Fallback Provider)"]
CLERK_CHECK -->|"No or not JWT"| ANON["👤 Anonymous<br/>(10 req/min)"]
CLERK_CHECK -->|"No or not JWT"| ANON["Anonymous<br/>(10 req/min)"]

CLERK -->|"Valid JWT"| CLERK_OK["✅ Authenticated<br/>(clerk-jwt method)<br/>⚠️ Deprecation warning logged"]
CLERK -->|"Invalid JWT"| REJECT4["❌ 401 Rejected"]
CLERK -->|"Valid JWT"| CLERK_OK["Authenticated<br/>(clerk-jwt method)<br/>Deprecation warning logged"]
CLERK -->|"Invalid JWT"| REJECT4["401 Rejected"]
CLERK -->|"No credentials"| ANON

style REQ fill:#e8f4f8,stroke:#2196F3
style AUTH_OK fill:#e8f5e9,stroke:#4CAF50
style BA_OK fill:#e8f5e9,stroke:#4CAF50
style CLERK_OK fill:#fff3e0,stroke:#FF9800
style ANON fill:#f5f5f5,stroke:#9E9E9E
style REJECT fill:#ffebee,stroke:#F44336
style REJECT2 fill:#ffebee,stroke:#F44336
style REJECT3 fill:#ffebee,stroke:#F44336
style REJECT4 fill:#ffebee,stroke:#F44336
style REQ fill:#37474f,stroke:#263238,color:#fff
style AUTH_OK fill:#1b5e20,stroke:#0a3010,color:#fff
style BA_OK fill:#1b5e20,stroke:#0a3010,color:#fff
style CLERK_OK fill:#b84000,stroke:#7a2900,color:#fff
style ANON fill:#37474f,stroke:#263238,color:#fff
style REJECT fill:#c62828,stroke:#8e1c1c,color:#fff
style REJECT2 fill:#c62828,stroke:#8e1c1c,color:#fff
style REJECT3 fill:#c62828,stroke:#8e1c1c,color:#fff
style REJECT4 fill:#c62828,stroke:#8e1c1c,color:#fff
```

---
Expand Down Expand Up @@ -343,7 +343,7 @@ The Clerk → Better Auth migration follows a phased approach:
gantt
title Clerk → Better Auth Migration
dateFormat YYYY-MM-DD
axisFormat %b %Y
axisFormat %Y-%m-%d

section Phase 1: Foundation
Prisma adapter + Better Auth setup :done, p1a, 2025-03-01, 14d
Expand Down
38 changes: 19 additions & 19 deletions docs/cloudflare/CLOUDFLARE_WORKFLOWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -614,12 +614,12 @@ flowchart TD

Error --> Complete

style Validate fill:#e1f5ff
style Compile fill:#fff9c4
style Cache fill:#c8e6c9
style Metrics fill:#e1f5ff
style Complete fill:#4caf50
style Error fill:#ffcdd2
style Validate fill:#1a237e,color:#fff
style Compile fill:#b8860b,color:#fff
style Cache fill:#1b5e20,color:#fff
style Metrics fill:#1a237e,color:#fff
style Complete fill:#1b5e20,color:#fff
style Error fill:#c62828,color:#fff
```

### Batch Workflow with Chunking
Expand Down Expand Up @@ -648,11 +648,11 @@ flowchart TD
Chunk2Done[Chunk 2 Complete] --> Metrics[Step: update-batch-metrics]
Metrics --> Complete[Return Batch Result]

style ValidateBatch fill:#e1f5ff
style Chunk1 fill:#fff9c4
style Chunk2 fill:#fff9c4
style Metrics fill:#e1f5ff
style Complete fill:#4caf50
style ValidateBatch fill:#1a237e,color:#fff
style Chunk1 fill:#b8860b,color:#fff
style Chunk2 fill:#b8860b,color:#fff
style Metrics fill:#1a237e,color:#fff
style Complete fill:#1b5e20,color:#fff
```

### Health Monitoring Workflow
Expand All @@ -673,14 +673,14 @@ flowchart TD

Store --> Complete[Return Health Result]

style LoadHistory fill:#e1f5ff
style CheckSource1 fill:#fff9c4
style CheckSource2 fill:#fff9c4
style CheckSourceN fill:#fff9c4
style Analyze fill:#ffe0b2
style SendAlerts fill:#ffcdd2
style Store fill:#c8e6c9
style Complete fill:#4caf50
style LoadHistory fill:#1a237e,color:#fff
style CheckSource1 fill:#b8860b,color:#fff
style CheckSource2 fill:#b8860b,color:#fff
style CheckSourceN fill:#b8860b,color:#fff
style Analyze fill:#b84000,color:#fff
style SendAlerts fill:#c62828,color:#fff
style Store fill:#1b5e20,color:#fff
style Complete fill:#1b5e20,color:#fff
```

---
Expand Down
Loading
Loading