# govza/haramblock architecture

> Architecture diagram of the GitHub repository govza/haramblock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/govza/haramblock
- Repository: https://github.com/govza/haramblock

## Overview

Haram Block is a cross-browser extension that applies per-site policies to detect and mask inappropriate images, GIFs, and video. The main path is webpage media discovery in the content script, policy-based processing and inference requests over background RPC, then prediction-driven overlays. Users configure site policy, strictness, and masking through the popup or options page; host settings and predictions are persisted in browser storage. The graph includes the documented video path and ONNX inference layer. Some subsystem links are based on documented capabilities and tree structure; unsampled implementation details are left unwired.

Main entry points: [`utils/messaging/services/backgroundRpc.ts`](https://github.com/govza/haramblock/blob/master/utils/messaging/services/backgroundRpc.ts) (Background RPC), [`entrypoints/content/core/MediaPipeline.ts`](https://github.com/govza/haramblock/blob/master/entrypoints/content/core/MediaPipeline.ts) (Media pipeline), [`entrypoints/background/services/inferenceOrchestrationService.ts`](https://github.com/govza/haramblock/blob/master/entrypoints/background/services/inferenceOrchestrationService.ts) (Inference orchestration), [`entrypoints/content/core/ImageProcessor.ts`](https://github.com/govza/haramblock/blob/master/entrypoints/content/core/ImageProcessor.ts) (Image processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["Page processing"]
  node_content["Content bootstrap<br/>[index.ts]"]
  node_pipeline["Media pipeline<br/>[MediaPipeline.ts]"]
  node_discovery["DOM media discovery<br/>[DomObserver.ts]"]
  node_image["Image processing<br/>[ImageProcessor.ts]"]
  node_video["Video processing<br/>[VideoProcessor.ts]"]
  node_sampling["Video frame sampling<br/>[sample.ts]"]
  node_masking["Prediction overlays"]
end

subgraph group_inference["Background inference"]
  node_rpc["Background RPC<br/>[backgroundRpc.ts]"]
  node_orchestration["Inference orchestration"]
  node_runtime["ONNX inference<br/>[prediction.ts]"]
  node_model["Model management<br/>[modelService.ts]"]
end

subgraph group_settings["Policy and settings"]
  node_popup["Popup controls<br/>[App.tsx]"]
  node_options["Options controls<br/>[App.tsx]"]
  node_hostservice["Host settings service"]
end

subgraph group_state["Persistence"]
  node_hostrepo["Host settings repository"]
  node_predictionstore["Prediction repositories"]
  node_database[("IndexedDB and session storage<br/>[db.ts]")]
end

node_webpage(("Visited webpage"))

node_webpage -->|"provides DOM"| node_discovery
node_content -->|"starts"| node_pipeline
node_pipeline -->|"observes media"| node_discovery
node_pipeline -->|"routes images"| node_image
node_pipeline -->|"routes video"| node_video
node_image -->|"requests inference"| node_rpc
node_video -->|"samples frames"| node_sampling
node_sampling -->|"sends frames"| node_rpc
node_rpc -->|"dispatches requests"| node_orchestration
node_orchestration -->|"runs inference"| node_runtime
node_orchestration -->|"reads and writes predictions"| node_predictionstore
node_orchestration -->|"returns predictions"| node_rpc
node_pipeline -->|"applies verdicts"| node_masking
node_popup -->|"reads and updates settings"| node_rpc
node_options -->|"reads and updates settings"| node_rpc
node_rpc -->|"dispatches settings"| node_hostservice
node_hostservice -->|"reads and writes"| node_hostrepo
node_hostrepo -->|"persists settings"| node_database
node_predictionstore -->|"persists predictions"| node_database
node_model -->|"configures model"| node_runtime

click node_content "https://github.com/govza/haramblock/blob/master/entrypoints/content/index.ts"
click node_pipeline "https://github.com/govza/haramblock/blob/master/entrypoints/content/core/MediaPipeline.ts"
click node_discovery "https://github.com/govza/haramblock/blob/master/entrypoints/content/core/DomObserver.ts"
click node_image "https://github.com/govza/haramblock/blob/master/entrypoints/content/core/ImageProcessor.ts"
click node_video "https://github.com/govza/haramblock/blob/master/entrypoints/content/core/VideoProcessor.ts"
click node_sampling "https://github.com/govza/haramblock/blob/master/entrypoints/content/video/sampling/sample.ts"
click node_masking "https://github.com/govza/haramblock/blob/master/entrypoints/content/presentation/imageMaskOverlay.ts"
click node_rpc "https://github.com/govza/haramblock/blob/master/utils/messaging/services/backgroundRpc.ts"
click node_orchestration "https://github.com/govza/haramblock/blob/master/entrypoints/background/services/inferenceOrchestrationService.ts"
click node_runtime "https://github.com/govza/haramblock/blob/master/utils/inference/runtimes/onnx/prediction.ts"
click node_model "https://github.com/govza/haramblock/blob/master/entrypoints/background/services/modelService.ts"
click node_popup "https://github.com/govza/haramblock/blob/master/entrypoints/popup/App.tsx"
click node_options "https://github.com/govza/haramblock/blob/master/entrypoints/options/App.tsx"
click node_hostservice "https://github.com/govza/haramblock/blob/master/entrypoints/background/services/hostSettingsService.ts"
click node_hostrepo "https://github.com/govza/haramblock/blob/master/utils/db/hostSettingsRepository.ts"
click node_predictionstore "https://github.com/govza/haramblock/blob/master/utils/db/imagePredictionRepository.ts"
click node_database "https://github.com/govza/haramblock/blob/master/utils/db/db.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content,node_pipeline,node_discovery,node_image,node_video,node_sampling,node_masking toneBlue
class node_rpc,node_orchestration,node_runtime,node_model toneAmber
class node_popup,node_options,node_hostservice toneMint
class node_hostrepo,node_predictionstore,node_database toneRose
class node_webpage toneIndigo
```

## Components

### Page processing

- [Content bootstrap](https://github.com/govza/haramblock/blob/master/entrypoints/content/index.ts): `entrypoints/content/index.ts`
- [Media pipeline](https://github.com/govza/haramblock/blob/master/entrypoints/content/core/MediaPipeline.ts): `entrypoints/content/core/MediaPipeline.ts`
- [DOM media discovery](https://github.com/govza/haramblock/blob/master/entrypoints/content/core/DomObserver.ts): `entrypoints/content/core/DomObserver.ts`
- [Image processing](https://github.com/govza/haramblock/blob/master/entrypoints/content/core/ImageProcessor.ts): `entrypoints/content/core/ImageProcessor.ts`
- [Video processing](https://github.com/govza/haramblock/blob/master/entrypoints/content/core/VideoProcessor.ts): `entrypoints/content/core/VideoProcessor.ts`
- [Video frame sampling](https://github.com/govza/haramblock/blob/master/entrypoints/content/video/sampling/sample.ts): `entrypoints/content/video/sampling/sample.ts`
- [Prediction overlays](https://github.com/govza/haramblock/blob/master/entrypoints/content/presentation/imageMaskOverlay.ts): `entrypoints/content/presentation/imageMaskOverlay.ts`

### Background inference

- [Background RPC](https://github.com/govza/haramblock/blob/master/utils/messaging/services/backgroundRpc.ts): `utils/messaging/services/backgroundRpc.ts`
- [Inference orchestration](https://github.com/govza/haramblock/blob/master/entrypoints/background/services/inferenceOrchestrationService.ts): `entrypoints/background/services/inferenceOrchestrationService.ts`
- [ONNX inference](https://github.com/govza/haramblock/blob/master/utils/inference/runtimes/onnx/prediction.ts): `utils/inference/runtimes/onnx/prediction.ts`
- [Model management](https://github.com/govza/haramblock/blob/master/entrypoints/background/services/modelService.ts): `entrypoints/background/services/modelService.ts`

### Policy and settings

- [Popup controls](https://github.com/govza/haramblock/blob/master/entrypoints/popup/App.tsx): `entrypoints/popup/App.tsx`
- [Options controls](https://github.com/govza/haramblock/blob/master/entrypoints/options/App.tsx): `entrypoints/options/App.tsx`
- [Host settings service](https://github.com/govza/haramblock/blob/master/entrypoints/background/services/hostSettingsService.ts): `entrypoints/background/services/hostSettingsService.ts`

### Persistence

- [Host settings repository](https://github.com/govza/haramblock/blob/master/utils/db/hostSettingsRepository.ts): `utils/db/hostSettingsRepository.ts`
- [Prediction repositories](https://github.com/govza/haramblock/blob/master/utils/db/imagePredictionRepository.ts): `utils/db/imagePredictionRepository.ts`
- [IndexedDB and session storage](https://github.com/govza/haramblock/blob/master/utils/db/db.ts): `utils/db/db.ts`

### Other components

- **Visited webpage**

## Connections

- Visited webpage → DOM media discovery: provides DOM
- Content bootstrap → Media pipeline: starts
- Media pipeline → DOM media discovery: observes media
- Media pipeline → Image processing: routes images
- Media pipeline → Video processing: routes video
- Image processing → Background RPC: requests inference
- Video processing → Video frame sampling: samples frames
- Video frame sampling → Background RPC: sends frames
- Background RPC → Inference orchestration: dispatches requests
- Inference orchestration → ONNX inference: runs inference
- Inference orchestration → Prediction repositories: reads and writes predictions
- Inference orchestration → Background RPC: returns predictions
- Media pipeline → Prediction overlays: applies verdicts
- Popup controls → Background RPC: reads and updates settings
- Options controls → Background RPC: reads and updates settings
- Background RPC → Host settings service: dispatches settings
- Host settings service → Host settings repository: reads and writes
- Host settings repository → IndexedDB and session storage: persists settings
- Prediction repositories → IndexedDB and session storage: persists predictions
- Model management → ONNX inference: configures model