# wxk-ai/genguard architecture

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

- Interactive diagram: https://gitdiagram.com/wxk-ai/genguard
- Repository: https://github.com/wxk-ai/genguard

## Overview

1. **What this repository is**
   - GenGuard is a Chrome Manifest V3 browser extension that runs entirely on-device.
   - Its purpose is to detect PII/confidential data before the user submits text into GenAI sites such as ChatGPT and Gemini.
   - The architecture is centered on local inference and local browser integration, not a backend service.

2. **High-level extension shape**
   - The repo splits into three main extension surfaces:
     - **Content scripts** in `src/content-scripts` that attach to target pages.
     - **Background/service worker** logic in `src/background/service-worker.ts` for extension-wide orchestration.
     - **Side panel UI** in `src/sidepanel` for user controls, scoring thresholds, and status.
   - `src/App.tsx` / `src/main.tsx` and `src/sidepanel/*` indicate React-based UI entry points, while Vite builds the extension bundle.

3. **User-facing runtime flow**
   - The likely primary flow is: user types into a GenAI prompt box → content script observes/reads the text → core detection pipeline scores and annotates it → highlights/redactions are shown inline.
   - The side panel acts as the control plane: enabling/disabling protection, adjusting risk thresholds, and viewing state/history.
   - The background service worker is the extension coordinator, handling MV3 lifecycle constraints and shared Chrome API interactions.

4. **Page integration boundary**
   - `src/content-scripts/chatgpt-injector.ts` and `src/content-scripts/gemini-injector.ts` show site-specific integration points.
   - `src/content-scripts/inline-highlighter.ts` suggests a UI overlay layer for marking detected spans directly inside text inputs or prompt editors.
   - These scripts are the boundary between the extension and the host web app DOM, where detection results become visible to the user.

5. **Core detection engine**
   - `src/core/engine.ts` is the central orchestration layer that probably combines multiple detection strategies into one scan result.
   - The engine feeds text through detectors, aggregates findings, and likely produces the risk score and redaction/highlight metadata used by the UI.
   - This is the main internal boundary between extension/UI code and the ML/text-analysis subsystem.

6. **Detector subsystem**
   - `src/core/detectors` contains multiple detection approaches:
     - `regex-detector.ts` for deterministic pattern matching.
     - `ner-detector.ts` for model-based named entity recognition.
     - `context-scorer.ts` for contextual/risk scoring around found entities.
     - `pii-patterns.json` for curated PII patterns.
   - `ner-model-contract.ts` defines the model interface, which keeps the ML runtime decoupled from the rest of the app.
   - Architecturally, this is a layered detection stack: fast rules first, then deeper semantic analysis.

7. **Model and tokenizer runtime**
   - `src/lib/ort-engine.ts` is the bridge to ONNX Runtime Web, which is bundled under `public/ort/`.
   - `src/core/tokenizer/sentencepiece-tokenizer.ts` is a custom tokenizer implementation in TypeScript, used to keep inference fully local and avoid heavier third-party wrappers.
   - `src/lib/model-store.ts` likely manages loading/caching of model assets from `public/models/`, and `src/core/types.ts` defines shared contracts for detections and scan output.

8. **OCR and document extraction**
   - The repository supports non-text inputs through `src/core/extractors`.
   - `pdf-extractor.ts` indicates PDF text extraction, likely using a bundled PDF worker or browser-side PDF parsing.
   - `image-ocr.ts` and the `ocr/` pipeline files (`ocr-engine.ts`, `ocr-pipeline.ts`, preprocess/postprocess/CTC decode) show a full offline OCR stack for screenshots or images.
   - This means the scan pipeline can ingest text from multiple modalities before it reaches the detectors.

9. **Persistence and local history**
   - `src/lib/history-store.ts` and `src/lib/model-store.ts` suggest browser-local persistence for scan history, state, and model availability.
   - Given the zero-knowledge design, persistence is expected to stay inside browser storage rather than any remote database.
   - The extension likely uses Chrome storage APIs to remember user settings, thresholds, and recent scan outcomes.

10. **Operational model and security boundary**
    - The README emphasizes that no user content leaves the browser unless explicitly permitted.
    - There are no cloud APIs, telemetry pipelines, or server-side components in the tree, which is a major architectural constraint.
    - The security boundary is therefore local-only: host page DOM input → extension scripts → local ML/rule engine → local UI feedback.

11. **Build and packaging**
    - The project uses **TypeScript + React + Vite** with Chrome extension packaging under MV3.
    - `public/ort/*` contains prebuilt ONNX Runtime WASM artifacts, and `manifest.json` defines the extension runtime contract.
    - `package.json`, `vite.config.ts`, and the separate `sidepanel/index.html` point to a multi-entry build that produces the extension bundle in `dist/`.

12. **Key architectural diagram anchors**
    - Draw the main external boundary as “Chrome browser / target GenAI pages.”
    - Inside the extension, show three zones: **content scripts**, **service worker**, and **side panel UI**.
    - Connect them to the shared **core pipeline** (`engine`, detectors, OCR, tokenizer, ONNX runtime).
    - Add local persistence for settings/history and local model assets as separate on-device storage layers.

Main entry points: [`src/core/engine.ts`](https://github.com/wxk-ai/genguard/blob/main/src/core/engine.ts) (Scan engine), [`src/core/detectors/ner-detector.ts`](https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/ner-detector.ts) (NER detector), [`src/background/service-worker.ts`](https://github.com/wxk-ai/genguard/blob/main/src/background/service-worker.ts) (Service worker), [`src/content-scripts/chatgpt-injector.ts`](https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/chatgpt-injector.ts) (ChatGPT hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_browser["Browser boundary"]
  node_browser_pages["GenAI pages<br/>host pages"]
end

subgraph group_group_extension["Extension surfaces"]
  node_content_chatgpt["ChatGPT hook<br/>content injector"]
  node_content_gemini["Gemini hook<br/>content injector<br/>[gemini-injector.ts]"]
  node_content_highlighter["Inline marks<br/>overlay UI"]
  node_service_worker["Service worker<br/>MV3 orchestrator<br/>[service-worker.ts]"]
  node_sidepanel_app["Side panel<br/>React control UI<br/>[App.tsx]"]
  node_sidepanel_main["Panel entry<br/>UI bootstrap<br/>[main.tsx]"]
  node_app_main["App entry<br/>UI bootstrap<br/>[main.tsx]"]
end

subgraph group_group_core["Core pipeline"]
  node_engine["Scan engine<br/>pipeline orchestrator<br/>[engine.ts]"]
  node_regex_detector["Regex rules<br/>pattern detector<br/>[regex-detector.ts]"]
  node_ner_detector["NER detector<br/>model detector<br/>[ner-detector.ts]"]
  node_context_scorer["Context score<br/>risk scorer<br/>[context-scorer.ts]"]
  node_ocr_pipeline["OCR pipeline<br/>offline OCR<br/>[ocr-pipeline.ts]"]
  node_pdf_extractor["PDF extractor<br/>text extractor<br/>[pdf-extractor.ts]"]
  node_tokenizer["Tokenizer"]
end

subgraph group_group_storage["Local assets"]
  node_ort_engine["ORT bridge<br/>onnx runtime bridge<br/>[ort-engine.ts]"]
  node_model_store["Model store<br/>asset cache<br/>[model-store.ts]"]
  node_history_store["History store<br/>local persistence<br/>[history-store.ts]"]
  node_public_models[("Model assets<br/>local files")]
  node_public_ort[("ORT WASM<br/>runtime assets")]
end

subgraph group_group_build["Build"]
  node_manifest["Manifest<br/>[manifest.json]"]
  node_vite_config["Vite config<br/>build config<br/>[vite.config.ts]"]
end

node_browser_pages -->|"injects"| node_content_chatgpt
node_browser_pages -->|"injects"| node_content_gemini
node_content_chatgpt -->|"renders"| node_content_highlighter
node_content_gemini -->|"renders"| node_content_highlighter
node_content_chatgpt -->|"scans text"| node_engine
node_content_gemini -->|"scans text"| node_engine
node_service_worker -->|"coordinates"| node_engine
node_sidepanel_app -->|"reads state"| node_history_store
node_sidepanel_app -->|"controls"| node_service_worker
node_app_main -->|"boots"| node_sidepanel_app
node_engine -->|"extracts"| node_pdf_extractor
node_engine -->|"extracts"| node_ocr_pipeline
node_engine -->|"applies"| node_regex_detector
node_engine -->|"applies"| node_ner_detector
node_engine -->|"scores"| node_context_scorer
node_ner_detector -->|"tokenizes"| node_tokenizer
node_ner_detector -->|"runs on"| node_ort_engine
node_ort_engine -->|"loads"| node_public_ort
node_model_store -->|"loads"| node_public_models
node_ner_detector -->|"fetches model"| node_model_store
node_service_worker -->|"persists"| node_history_store
node_manifest -->|"declares"| node_service_worker
node_manifest -->|"declares"| node_sidepanel_main
node_vite_config -->|"bundles"| node_app_main
node_vite_config -->|"bundles"| node_sidepanel_main

click node_content_chatgpt "https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/chatgpt-injector.ts"
click node_content_gemini "https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/gemini-injector.ts"
click node_content_highlighter "https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/inline-highlighter.ts"
click node_service_worker "https://github.com/wxk-ai/genguard/blob/main/src/background/service-worker.ts"
click node_sidepanel_app "https://github.com/wxk-ai/genguard/blob/main/src/sidepanel/App.tsx"
click node_sidepanel_main "https://github.com/wxk-ai/genguard/blob/main/src/sidepanel/main.tsx"
click node_app_main "https://github.com/wxk-ai/genguard/blob/main/src/main.tsx"
click node_engine "https://github.com/wxk-ai/genguard/blob/main/src/core/engine.ts"
click node_regex_detector "https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/regex-detector.ts"
click node_ner_detector "https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/ner-detector.ts"
click node_context_scorer "https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/context-scorer.ts"
click node_ocr_pipeline "https://github.com/wxk-ai/genguard/blob/main/src/core/extractors/ocr/ocr-pipeline.ts"
click node_pdf_extractor "https://github.com/wxk-ai/genguard/blob/main/src/core/extractors/pdf-extractor.ts"
click node_tokenizer "https://github.com/wxk-ai/genguard/blob/main/src/core/tokenizer/sentencepiece-tokenizer.ts"
click node_ort_engine "https://github.com/wxk-ai/genguard/blob/main/src/lib/ort-engine.ts"
click node_model_store "https://github.com/wxk-ai/genguard/blob/main/src/lib/model-store.ts"
click node_history_store "https://github.com/wxk-ai/genguard/blob/main/src/lib/history-store.ts"
click node_public_models "https://github.com/wxk-ai/genguard/tree/main/public"
click node_public_ort "https://github.com/wxk-ai/genguard/blob/main/public/ort/ort-wasm-simd-threaded.mjs"
click node_manifest "https://github.com/wxk-ai/genguard/blob/main/manifest.json"
click node_vite_config "https://github.com/wxk-ai/genguard/blob/main/vite.config.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_browser_pages toneBlue
class node_content_chatgpt,node_content_gemini,node_content_highlighter,node_service_worker,node_sidepanel_app,node_sidepanel_main,node_app_main toneAmber
class node_engine,node_regex_detector,node_ner_detector,node_context_scorer,node_ocr_pipeline,node_pdf_extractor,node_tokenizer toneMint
class node_ort_engine,node_model_store,node_history_store,node_public_models,node_public_ort toneRose
class node_manifest,node_vite_config toneIndigo
```

## Components

### Browser boundary

Host pages and Chrome runtime surfaces the extension interacts with

- **GenAI pages**: host pages · Target sites where user prompt text is entered and inspected

### Extension surfaces

Manifest V3 entry points and UI surfaces inside the extension

- [ChatGPT hook](https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/chatgpt-injector.ts): content injector · Site-specific integration for ChatGPT prompt areas · `src/content-scripts/chatgpt-injector.ts`
- [Gemini hook](https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/gemini-injector.ts): content injector · Site-specific integration for Gemini prompt areas · `src/content-scripts/gemini-injector.ts`
- [Inline marks](https://github.com/wxk-ai/genguard/blob/main/src/content-scripts/inline-highlighter.ts): overlay UI · Renders detected spans and redactions inside page editors · `src/content-scripts/inline-highlighter.ts`
- [Service worker](https://github.com/wxk-ai/genguard/blob/main/src/background/service-worker.ts): MV3 orchestrator · Extension-wide coordination and Chrome API boundary · `src/background/service-worker.ts`
- [Side panel](https://github.com/wxk-ai/genguard/blob/main/src/sidepanel/App.tsx): React control UI · User-facing controls for protection state and thresholds · `src/sidepanel/App.tsx`
- [Panel entry](https://github.com/wxk-ai/genguard/blob/main/src/sidepanel/main.tsx): UI bootstrap · Side panel runtime entry point · `src/sidepanel/main.tsx`
- [App entry](https://github.com/wxk-ai/genguard/blob/main/src/main.tsx): UI bootstrap · Main extension UI entry point for shared React rendering · `src/main.tsx`

### Core pipeline

Shared scanning, detection, and extraction logic

- [Scan engine](https://github.com/wxk-ai/genguard/blob/main/src/core/engine.ts): pipeline orchestrator · Coordinates extraction, detection, and scoring · `src/core/engine.ts`
- [Regex rules](https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/regex-detector.ts): pattern detector · Deterministic PII pattern matching · `src/core/detectors/regex-detector.ts`
- [NER detector](https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/ner-detector.ts): model detector · Named-entity detection backed by a local model contract · `src/core/detectors/ner-detector.ts`
- [Context score](https://github.com/wxk-ai/genguard/blob/main/src/core/detectors/context-scorer.ts): risk scorer · Adds surrounding-text risk weighting and confidence · `src/core/detectors/context-scorer.ts`
- [OCR pipeline](https://github.com/wxk-ai/genguard/blob/main/src/core/extractors/ocr/ocr-pipeline.ts): offline OCR · Preprocesses, decodes, and postprocesses image text extraction · `src/core/extractors/ocr/ocr-pipeline.ts`
- [PDF extractor](https://github.com/wxk-ai/genguard/blob/main/src/core/extractors/pdf-extractor.ts): text extractor · Extracts text from PDF documents before scanning · `src/core/extractors/pdf-extractor.ts`
- [Tokenizer](https://github.com/wxk-ai/genguard/blob/main/src/core/tokenizer/sentencepiece-tokenizer.ts): sentencepiece tokenizer · Local tokenization used by model-based inference · `src/core/tokenizer/sentencepiece-tokenizer.ts`

### Local assets

On-device persistence and bundled model/runtime assets

- [ORT bridge](https://github.com/wxk-ai/genguard/blob/main/src/lib/ort-engine.ts): onnx runtime bridge · Connects the app to ONNX Runtime Web execution · `src/lib/ort-engine.ts`
- [Model store](https://github.com/wxk-ai/genguard/blob/main/src/lib/model-store.ts): asset cache · Loads and caches local model assets · `src/lib/model-store.ts`
- [History store](https://github.com/wxk-ai/genguard/blob/main/src/lib/history-store.ts): local persistence · Persists settings and scan history in browser storage · `src/lib/history-store.ts`
- [Model assets](https://github.com/wxk-ai/genguard/tree/main/public): local files · Bundled local model files used by inference · `public`
- [ORT WASM](https://github.com/wxk-ai/genguard/blob/main/public/ort/ort-wasm-simd-threaded.mjs): runtime assets · Prebuilt ONNX Runtime WebAssembly artifacts · `public/ort/ort-wasm-simd-threaded.mjs`

### Build

Top-level packaging and entry configuration

- [Manifest](https://github.com/wxk-ai/genguard/blob/main/manifest.json): extension manifest · Declares MV3 extension entry points and permissions · `manifest.json`
- [Vite config](https://github.com/wxk-ai/genguard/blob/main/vite.config.ts): build config · Builds the multi-entry extension bundle · `vite.config.ts`

## Connections

- GenAI pages → ChatGPT hook: injects · Content script attaches to ChatGPT pages
- GenAI pages → Gemini hook: injects · Content script attaches to Gemini pages
- ChatGPT hook → Inline marks: renders · Detected spans are marked inline in the editor
- Gemini hook → Inline marks: renders · Detected spans are marked inline in the editor
- ChatGPT hook → Scan engine: scans text · Observed prompt text is sent into the detection pipeline
- Gemini hook → Scan engine: scans text · Observed prompt text is sent into the detection pipeline
- Service worker → Scan engine: coordinates · Background worker orchestrates shared scan requests and lifecycle
- Side panel → History store: reads state · UI loads saved settings and recent outcomes
- Side panel → Service worker: controls · Panel toggles protection and updates thresholds through the worker
- App entry → Side panel: boots · Shared React entry points into the UI layer
- Scan engine → PDF extractor: extracts · PDF text is normalized before detection
- Scan engine → OCR pipeline: extracts · Image and screenshot text is recovered offline
- Scan engine → Regex rules: applies · Rule-based patterns run as the fast first pass
- Scan engine → NER detector: applies · Model-based entity detection augments rules
- Scan engine → Context score: scores · Findings are reweighted by surrounding context
- NER detector → Tokenizer: tokenizes · NER model input is prepared locally
- NER detector → ORT bridge: runs on · Inference executes through the ONNX Runtime bridge
- ORT bridge → ORT WASM: loads · Runtime assets are loaded from bundled WASM files
- Model store → Model assets: loads · Local model artifacts are fetched from bundled assets
- NER detector → Model store: fetches model · Model lifecycle and caching are mediated through the store
- Service worker → History store: persists · Shared settings and scan history are kept locally
- Manifest → Service worker: declares · MV3 background entry point is registered in the manifest
- Manifest → Panel entry: declares · Side panel entry point is registered in the manifest
- Vite config → App entry: bundles · Build pipeline includes the main extension UI entry
- Vite config → Panel entry: bundles · Build pipeline includes the side panel entry
