# aloshdenny/reverse-synthid architecture

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

- Interactive diagram: https://gitdiagram.com/aloshdenny/reverse-synthid
- Repository: https://github.com/aloshdenny/reverse-synthid

## Overview

This repository is a research toolkit for analyzing SynthID image watermarks and generating watermark-reduced image variants, with a local drag-and-drop cleaner. The main workflow builds a spectral codebook from reference images, applies a selected bypass to input images, and can use manual Gemini detection tallies to recalibrate V4 carrier weights. Separate capabilities include watermark detection/extraction, investigation and analysis, and the desktop V3 workflow. Relationships involving unsampled modules are included only where the README or SOURCE INDEX supports them.

Main entry points: [`scripts/dissolve_batch.py`](https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/dissolve_batch.py) (Batch dissolver), [`gui/gui.py`](https://github.com/aloshdenny/reverse-synthid/blob/main/gui/gui.py) (Desktop cleaner), [`src/extraction/synthid_bypass_v4.py`](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_bypass_v4.py) (V4 consensus bypass), [`src/extraction/benchmark_extraction.py`](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/benchmark_extraction.py) (Extraction benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Watermark research"]
  node_investigation["Watermark investigation"]
  node_deep_analysis["Deep analysis"]
  node_codebook_finder["Codebook discovery"]
end

subgraph group_detect["Detection and extraction"]
  node_codebook_extractor["Codebook extraction"]
  node_robust_extractor["Robust detection"]
  node_benchmark["Extraction benchmark"]
end

subgraph group_bypass["Bypass and cleaning"]
  node_remover["Signature remover"]
  node_bypass_v3["Spectral bypass V3<br/>[synthid_bypass.py]"]
  node_vae["VAE regeneration<br/>[vae_regen.py]"]
  node_bypass_v4["V4 consensus bypass"]
  node_gui["Desktop cleaner<br/>[gui.py]"]
end

subgraph group_calibration["V4 calibration"]
  node_codebook_builder["Codebook builder"]
  node_codebook[("V4 spectral codebook")]
  node_batch["Batch dissolver<br/>[dissolve_batch.py]"]
  node_manifest["Variant manifest"]
  node_calibrator["Feedback calibration"]
end

node_user(("Image user"))
node_reference_data["Reference images"]
node_gemini(("Gemini detection app"))
node_feedback["Manual detection tally"]
node_cleaned["Cleaned image variants"]

node_user -->|"selects images"| node_gui
node_gui -->|"invokes bypass"| node_bypass_v3
node_gui -->|"invokes bypass"| node_bypass_v4
node_gui -->|"saves images"| node_cleaned
node_reference_data -->|"provides references"| node_codebook_builder
node_codebook_builder -->|"builds profiles"| node_bypass_v4
node_codebook_builder -->|"writes codebook"| node_codebook
node_user -->|"provides inputs"| node_batch
node_codebook -->|"loads codebook"| node_batch
node_batch -->|"runs variants"| node_bypass_v4
node_batch -->|"writes variants"| node_cleaned
node_batch -->|"writes manifest"| node_manifest
node_manifest -->|"joins feedback"| node_calibrator
node_feedback -->|"supplies tallies"| node_calibrator
node_calibrator -->|"updates weights"| node_codebook
node_gemini -->|"provides detection results"| node_feedback
node_bypass_v4 -->|"runs regeneration"| node_vae
node_bypass_v3 -->|"uses extractor"| node_robust_extractor
node_remover -->|"uses extractor"| node_robust_extractor
node_benchmark -->|"benchmarks detection"| node_robust_extractor
node_benchmark -->|"benchmarks removal"| node_remover
node_benchmark -->|"benchmarks extraction"| node_codebook_extractor
node_user -.->|"provides evidence"| node_investigation
node_user -.->|"provides images"| node_deep_analysis
node_user -.->|"provides images"| node_codebook_finder

click node_investigation "https://github.com/aloshdenny/reverse-synthid/tree/main/watermark_investigation"
click node_deep_analysis "https://github.com/aloshdenny/reverse-synthid/blob/main/src/analysis/deep_synthid_analysis.py"
click node_codebook_finder "https://github.com/aloshdenny/reverse-synthid/blob/main/src/analysis/synthid_codebook_finder.py"
click node_codebook_extractor "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_codebook_extractor.py"
click node_robust_extractor "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/robust_extractor.py"
click node_benchmark "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/benchmark_extraction.py"
click node_remover "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/watermark_remover.py"
click node_bypass_v3 "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_bypass.py"
click node_vae "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/vae_regen.py"
click node_bypass_v4 "https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_bypass_v4.py"
click node_gui "https://github.com/aloshdenny/reverse-synthid/blob/main/gui/gui.py"
click node_codebook_builder "https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/build_codebook_v4.py"
click node_codebook "https://github.com/aloshdenny/reverse-synthid/blob/main/artifacts/spectral_codebook_v4.npz"
click node_batch "https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/dissolve_batch.py"
click node_calibrator "https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/calibrate_from_feedback.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_investigation,node_deep_analysis,node_codebook_finder,node_user toneBlue
class node_codebook_extractor,node_robust_extractor,node_benchmark toneAmber
class node_remover,node_bypass_v3,node_vae,node_bypass_v4,node_gui toneMint
class node_codebook_builder,node_codebook,node_batch,node_manifest,node_calibrator toneRose
class node_reference_data,node_gemini,node_feedback,node_cleaned toneIndigo
```

## Components

### Watermark research

- [Watermark investigation](https://github.com/aloshdenny/reverse-synthid/tree/main/watermark_investigation): `watermark_investigation`
- [Deep analysis](https://github.com/aloshdenny/reverse-synthid/blob/main/src/analysis/deep_synthid_analysis.py): `src/analysis/deep_synthid_analysis.py`
- [Codebook discovery](https://github.com/aloshdenny/reverse-synthid/blob/main/src/analysis/synthid_codebook_finder.py): `src/analysis/synthid_codebook_finder.py`

### Detection and extraction

- [Codebook extraction](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_codebook_extractor.py): `src/extraction/synthid_codebook_extractor.py`
- [Robust detection](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/robust_extractor.py): `src/extraction/robust_extractor.py`
- [Extraction benchmark](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/benchmark_extraction.py): `src/extraction/benchmark_extraction.py`

### Bypass and cleaning

- [Signature remover](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/watermark_remover.py): `src/extraction/watermark_remover.py`
- [Spectral bypass V3](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_bypass.py): `src/extraction/synthid_bypass.py`
- [VAE regeneration](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/vae_regen.py): `src/extraction/vae_regen.py`
- [V4 consensus bypass](https://github.com/aloshdenny/reverse-synthid/blob/main/src/extraction/synthid_bypass_v4.py): `src/extraction/synthid_bypass_v4.py`
- [Desktop cleaner](https://github.com/aloshdenny/reverse-synthid/blob/main/gui/gui.py): `gui/gui.py`

### V4 calibration

- [Codebook builder](https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/build_codebook_v4.py): `scripts/build_codebook_v4.py`
- [V4 spectral codebook](https://github.com/aloshdenny/reverse-synthid/blob/main/artifacts/spectral_codebook_v4.npz): `artifacts/spectral_codebook_v4.npz`
- [Batch dissolver](https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/dissolve_batch.py): `scripts/dissolve_batch.py`
- **Variant manifest**
- [Feedback calibration](https://github.com/aloshdenny/reverse-synthid/blob/main/scripts/calibrate_from_feedback.py): `scripts/calibrate_from_feedback.py`

### Other components

- **Image user**
- **Reference images**
- **Gemini detection app**
- **Manual detection tally**
- **Cleaned image variants**

## Connections

- Image user → Desktop cleaner: selects images (evidence: `gui/gui.py`)
- Desktop cleaner → Spectral bypass V3: invokes bypass (evidence: `gui/gui.py`)
- Desktop cleaner → V4 consensus bypass: invokes bypass (evidence: `gui/gui.py`)
- Desktop cleaner → Cleaned image variants: saves images (evidence: `gui/gui.py`)
- Reference images → Codebook builder: provides references (evidence: `README.md`)
- Codebook builder → V4 consensus bypass: builds profiles (evidence: `scripts/build_codebook_v4.py`)
- Codebook builder → V4 spectral codebook: writes codebook (evidence: `README.md`)
- Image user → Batch dissolver: provides inputs (evidence: `README.md`)
- V4 spectral codebook → Batch dissolver: loads codebook (evidence: `README.md`)
- Batch dissolver → V4 consensus bypass: runs variants (evidence: `scripts/dissolve_batch.py`)
- Batch dissolver → Cleaned image variants: writes variants (evidence: `README.md`)
- Batch dissolver → Variant manifest: writes manifest (evidence: `README.md`)
- Variant manifest → Feedback calibration: joins feedback (evidence: `scripts/calibrate_from_feedback.py`)
- Manual detection tally → Feedback calibration: supplies tallies (evidence: `scripts/calibrate_from_feedback.py`)
- Feedback calibration → V4 spectral codebook: updates weights (evidence: `README.md`)
- Gemini detection app → Manual detection tally: provides detection results (evidence: `README.md`)
- V4 consensus bypass → VAE regeneration: runs regeneration (evidence: `src/extraction/synthid_bypass_v4.py`)
- Spectral bypass V3 → Robust detection: uses extractor (evidence: `src/extraction/synthid_bypass.py`)
- Signature remover → Robust detection: uses extractor (evidence: `src/extraction/watermark_remover.py`)
- Extraction benchmark → Robust detection: benchmarks detection (evidence: `src/extraction/benchmark_extraction.py`)
- Extraction benchmark → Signature remover: benchmarks removal (evidence: `src/extraction/benchmark_extraction.py`)
- Extraction benchmark → Codebook extraction: benchmarks extraction (evidence: `src/extraction/benchmark_extraction.py`)
- Image user → Watermark investigation: provides evidence
- Image user → Deep analysis: provides images
- Image user → Codebook discovery: provides images