# aliestereroan/deeptrace architecture

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

- Interactive diagram: https://gitdiagram.com/aliestereroan/deeptrace
- Repository: https://github.com/aliestereroan/deeptrace

## Overview

DeepTrace is a Chromium extension for local AI-image detection. Its principal workflow starts with a page image or user scan request, routes the image through the background worker to offscreen ONNX inference, then returns a verdict for display. Separate branches provide history/export, settings and localization, provenance reading, and model certification/training. The README documents the extension flow; sampled source confirms offscreen scoring and provenance. Several UI and backend subsystem links are documented or indicated by the source index rather than sampled implementation.

Main entry points: [`extension/offscreen.js`](https://github.com/aliestereroan/deeptrace/blob/master/extension/offscreen.js) (Inference bridge), [`extension/background.js`](https://github.com/aliestereroan/deeptrace/blob/master/extension/background.js) (Message routing), [`extension/content.js`](https://github.com/aliestereroan/deeptrace/blob/master/extension/content.js) (Image scanning), [`extension/popup/popup.js`](https://github.com/aliestereroan/deeptrace/blob/master/extension/popup/popup.js) (Scan interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Scanning and UI"]
  node_content["Image scanning<br/>[content.js]"]
  node_background["Message routing<br/>[background.js]"]
  node_popup["Scan interface<br/>[popup.js]"]
end

subgraph group_inference["Local inference"]
  node_offscreen["Inference bridge<br/>[offscreen.js]"]
  node_scorer["ONNX scorer<br/>[scorer.js]"]
  node_preprocess["Image preprocessing<br/>[preprocess.js]"]
  node_provenance["Provenance reader<br/>[provenance.js]"]
  node_confidence["Confidence bands<br/>[confidence.js]"]
end

subgraph group_records["Results and preferences"]
  node_history["Scan history<br/>[history.js]"]
  node_settings["Extension settings<br/>[settings.js]"]
  node_i18n["Localization<br/>[i18n.js]"]
  node_theme["Theme handling<br/>[theme.js]"]
  node_help["Help page<br/>[help.js]"]
end

subgraph group_modelwork["Model development"]
  node_harvest["Photo harvesting"]
  node_degrade["Photo degradation"]
  node_real_score["Real-photo scoring"]
  node_frontier["Frontier scoring"]
  node_evaluation["Model certification"]
  node_training["Model fine-tuning"]
  node_export["ONNX export<br/>[export_onnx.py]"]
end

node_user(("Browser user"))
node_page["Web page images"]
node_onnx["ONNX Runtime Web"]
node_imagehost["Image host"]

node_user -->|"requests scan"| node_popup
node_user -->|"right-clicks image"| node_page
node_page -->|"exposes images"| node_content
node_content -->|"sends scan"| node_background
node_popup -.->|"requests scan"| node_background
node_background -->|"routes inference"| node_offscreen
node_offscreen -->|"fetches image bytes"| node_imagehost
node_offscreen -->|"reads metadata"| node_provenance
node_offscreen -->|"scores bytes"| node_scorer
node_scorer -->|"prepares tensor"| node_preprocess
node_scorer -->|"runs inference"| node_onnx
node_offscreen -->|"returns result"| node_background
node_background -->|"returns verdict"| node_content
node_content -->|"displays badge"| node_user
node_popup -.->|"views history"| node_history
node_history -->|"exports report"| node_user
node_settings -->|"offers controls"| node_user
node_harvest -->|"supplies photos"| node_degrade
node_real_score -.->|"scores photos"| node_frontier
node_evaluation -->|"scores candidates"| node_frontier
node_evaluation -->|"uses metrics"| node_real_score
node_training -.->|"exports checkpoint"| node_export
node_export -->|"checks agreement"| node_frontier

click node_content "https://github.com/aliestereroan/deeptrace/blob/master/extension/content.js"
click node_background "https://github.com/aliestereroan/deeptrace/blob/master/extension/background.js"
click node_popup "https://github.com/aliestereroan/deeptrace/blob/master/extension/popup/popup.js"
click node_offscreen "https://github.com/aliestereroan/deeptrace/blob/master/extension/offscreen.js"
click node_scorer "https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/scorer.js"
click node_preprocess "https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/preprocess.js"
click node_provenance "https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/provenance.js"
click node_confidence "https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/confidence.js"
click node_history "https://github.com/aliestereroan/deeptrace/blob/master/extension/history/history.js"
click node_settings "https://github.com/aliestereroan/deeptrace/blob/master/extension/settings/settings.js"
click node_i18n "https://github.com/aliestereroan/deeptrace/blob/master/extension/i18n.js"
click node_theme "https://github.com/aliestereroan/deeptrace/blob/master/extension/theme.js"
click node_help "https://github.com/aliestereroan/deeptrace/blob/master/extension/help/help.js"
click node_harvest "https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/harvest_real_photos.py"
click node_degrade "https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/degrade_real_photos.py"
click node_real_score "https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/score_real_photos.py"
click node_frontier "https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/frontier_wrapper.py"
click node_evaluation "https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/evaluate_frontier.py"
click node_training "https://github.com/aliestereroan/deeptrace/blob/master/backend/train/finetune/finetune_frontier.py"
click node_export "https://github.com/aliestereroan/deeptrace/blob/master/backend/train/finetune/export_onnx.py"

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_background,node_popup,node_user toneBlue
class node_offscreen,node_scorer,node_preprocess,node_provenance,node_confidence toneAmber
class node_history,node_settings,node_i18n,node_theme,node_help toneMint
class node_harvest,node_degrade,node_real_score,node_frontier,node_evaluation,node_training,node_export toneRose
class node_page,node_onnx,node_imagehost toneIndigo
```

## Components

### Scanning and UI

- [Image scanning](https://github.com/aliestereroan/deeptrace/blob/master/extension/content.js): `extension/content.js`
- [Message routing](https://github.com/aliestereroan/deeptrace/blob/master/extension/background.js): `extension/background.js`
- [Scan interface](https://github.com/aliestereroan/deeptrace/blob/master/extension/popup/popup.js): `extension/popup/popup.js`

### Local inference

- [Inference bridge](https://github.com/aliestereroan/deeptrace/blob/master/extension/offscreen.js): `extension/offscreen.js`
- [ONNX scorer](https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/scorer.js): `extension/lib/scorer.js`
- [Image preprocessing](https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/preprocess.js): `extension/lib/preprocess.js`
- [Provenance reader](https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/provenance.js): `extension/lib/provenance.js`
- [Confidence bands](https://github.com/aliestereroan/deeptrace/blob/master/extension/lib/confidence.js): `extension/lib/confidence.js`

### Results and preferences

- [Scan history](https://github.com/aliestereroan/deeptrace/blob/master/extension/history/history.js): `extension/history/history.js`
- [Extension settings](https://github.com/aliestereroan/deeptrace/blob/master/extension/settings/settings.js): `extension/settings/settings.js`
- [Localization](https://github.com/aliestereroan/deeptrace/blob/master/extension/i18n.js): `extension/i18n.js`
- [Theme handling](https://github.com/aliestereroan/deeptrace/blob/master/extension/theme.js): `extension/theme.js`
- [Help page](https://github.com/aliestereroan/deeptrace/blob/master/extension/help/help.js): `extension/help/help.js`

### Model development

- [Photo harvesting](https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/harvest_real_photos.py): `backend/evaluate/harvest_real_photos.py`
- [Photo degradation](https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/degrade_real_photos.py): `backend/evaluate/degrade_real_photos.py`
- [Real-photo scoring](https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/score_real_photos.py): `backend/evaluate/score_real_photos.py`
- [Frontier scoring](https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/frontier_wrapper.py): `backend/evaluate/frontier_wrapper.py`
- [Model certification](https://github.com/aliestereroan/deeptrace/blob/master/backend/evaluate/evaluate_frontier.py): `backend/evaluate/evaluate_frontier.py`
- [Model fine-tuning](https://github.com/aliestereroan/deeptrace/blob/master/backend/train/finetune/finetune_frontier.py): `backend/train/finetune/finetune_frontier.py`
- [ONNX export](https://github.com/aliestereroan/deeptrace/blob/master/backend/train/finetune/export_onnx.py): `backend/train/finetune/export_onnx.py`

### Other components

- **Browser user**
- **Web page images**
- **ONNX Runtime Web**
- **Image host**

## Connections

- Browser user → Scan interface: requests scan (evidence: `README.md`)
- Browser user → Web page images: right-clicks image (evidence: `README.md`)
- Web page images → Image scanning: exposes images (evidence: `README.md`)
- Image scanning → Message routing: sends scan (evidence: `README.md`)
- Scan interface → Message routing: requests scan
- Message routing → Inference bridge: routes inference (evidence: `README.md`)
- Inference bridge → Image host: fetches image bytes (evidence: `extension/offscreen.js`)
- Inference bridge → Provenance reader: reads metadata (evidence: `extension/offscreen.js`)
- Inference bridge → ONNX scorer: scores bytes (evidence: `extension/offscreen.js`)
- ONNX scorer → Image preprocessing: prepares tensor (evidence: `extension/lib/scorer.js`)
- ONNX scorer → ONNX Runtime Web: runs inference (evidence: `README.md`)
- Inference bridge → Message routing: returns result (evidence: `README.md`)
- Message routing → Image scanning: returns verdict (evidence: `README.md`)
- Image scanning → Browser user: displays badge (evidence: `README.md`)
- Scan interface → Scan history: views history
- Scan history → Browser user: exports report (evidence: `README.md`)
- Extension settings → Browser user: offers controls (evidence: `README.md`)
- Photo harvesting → Photo degradation: supplies photos (evidence: `backend/evaluate/degrade_real_photos.py`)
- Real-photo scoring → Frontier scoring: scores photos
- Model certification → Frontier scoring: scores candidates (evidence: `backend/evaluate/evaluate_frontier.py`)
- Model certification → Real-photo scoring: uses metrics (evidence: `backend/evaluate/evaluate_frontier.py`)
- Model fine-tuning → ONNX export: exports checkpoint
- ONNX export → Frontier scoring: checks agreement (evidence: `backend/train/finetune/export_onnx.py`)