# jasonkneen/pixelprovenance architecture

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

- Interactive diagram: https://gitdiagram.com/jasonkneen/pixelprovenance
- Repository: https://github.com/jasonkneen/pixelprovenance
- Video tour (about a minute): https://gitdiagram.com/jasonkneen/pixelprovenance/video

## Overview

PixelProvenance embeds component identity and optional source locations in visual patterns, then turns a selected UI element or crop into a package containing identity metadata and a PNG. Its main drop-in workflow is toolbar selection/cropping → identity and capture → package delivery; a separate decoder workflow scans PNGs against a supplied registry. React tags, Cluso integration, and the demo provide additional product surfaces. The README documents capabilities whose implementation was not sampled; links to those are limited to supported paths and evidence.

Main entry points: [`src/dropin/mount.ts`](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/mount.ts) (Drop-in mount), [`src/cluso/index.ts`](https://github.com/jasonkneen/pixelprovenance/blob/main/src/cluso/index.ts) (Cluso plugin), [`decoder/decode.ts`](https://github.com/jasonkneen/pixelprovenance/blob/main/decoder/decode.ts) (PNG decoder), [`src/demo.tsx`](https://github.com/jasonkneen/pixelprovenance/blob/main/src/demo.tsx) (Interactive demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Tagging and capture"]
  node_mount["Drop-in mount<br/>[mount.ts]"]
  node_toolbar["Selection toolbar<br/>[toolbar.ts]"]
  node_picker["Element picker<br/>[picker.ts]"]
  node_crop["Crop gesture<br/>[crop.ts]"]
  node_identity["Identity mapping<br/>[identity.ts]"]
  node_signals["Visual signals<br/>[signal.ts]"]
  node_capture_image["Screenshot capture<br/>[capture.ts]"]
end

subgraph group_analysis["Decode and analysis"]
  node_decoder["PNG decoder<br/>[decode.ts]"]
  node_pattern["Pattern engine<br/>[pattern.ts]"]
  node_spectral["Spectral analysis<br/>[spectral.ts]"]
  node_demo_analysis["Screenshot analysis<br/>[demo-analysis.ts]"]
end

subgraph group_integrations["Integrations"]
  node_react_tags["React tags<br/>[DevTag.tsx]"]
  node_cluso["Cluso plugin<br/>[index.ts]"]
  node_demo["Interactive demo<br/>[demo.tsx]"]
end

subgraph group_delivery["Package delivery"]
  node_package["Selection package<br/>[package.ts]"]
  node_transport["Package transport<br/>[transport.ts]"]
  node_receiver["Reference receiver<br/>[receive.ts]"]
  node_inbox[("Package files")]
end

node_site_user(("Website user"))
node_png_user(("PNG and registry"))
node_model_worker(("Model worker"))

node_site_user -->|"uses"| node_toolbar
node_mount -->|"renders"| node_toolbar
node_mount -->|"applies"| node_signals
node_toolbar -->|"dispatches modes"| node_mount
node_mount -->|"starts selection"| node_picker
node_mount -->|"starts cropping"| node_crop
node_mount -->|"resolves identity"| node_identity
node_mount -->|"captures region"| node_capture_image
node_mount -->|"verifies crop"| node_demo_analysis
node_mount -->|"creates package"| node_package
node_mount -->|"delivers package"| node_transport
node_transport -->|"POSTs package"| node_receiver
node_receiver -->|"writes files"| node_inbox
node_receiver -->|"returns status"| node_transport
node_png_user -->|"provides PNG and registry"| node_decoder
node_decoder -->|"generates patterns"| node_pattern
node_decoder -->|"detects carriers"| node_spectral
node_decoder -->|"returns matches"| node_png_user
node_react_tags -->|"generates signals"| node_pattern
node_cluso -->|"builds codebook"| node_identity
node_cluso -->|"applies signals"| node_signals
node_cluso -->|"captures screenshots"| node_capture_image
node_cluso -->|"analyzes screenshots"| node_demo_analysis
node_demo -->|"renders tags"| node_react_tags
node_demo -->|"analyzes crop"| node_demo_analysis
node_demo -.->|"demonstrates package use"| node_model_worker

click node_mount "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/mount.ts"
click node_toolbar "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/toolbar.ts"
click node_picker "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/picker.ts"
click node_crop "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/crop.ts"
click node_identity "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/identity.ts"
click node_signals "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/signal.ts"
click node_capture_image "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/capture.ts"
click node_package "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/package.ts"
click node_transport "https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/transport.ts"
click node_receiver "https://github.com/jasonkneen/pixelprovenance/blob/main/server/receive.ts"
click node_decoder "https://github.com/jasonkneen/pixelprovenance/blob/main/decoder/decode.ts"
click node_pattern "https://github.com/jasonkneen/pixelprovenance/blob/main/src/pattern.ts"
click node_spectral "https://github.com/jasonkneen/pixelprovenance/blob/main/src/spectral.ts"
click node_demo_analysis "https://github.com/jasonkneen/pixelprovenance/blob/main/src/demo-analysis.ts"
click node_react_tags "https://github.com/jasonkneen/pixelprovenance/blob/main/src/DevTag.tsx"
click node_cluso "https://github.com/jasonkneen/pixelprovenance/blob/main/src/cluso/index.ts"
click node_demo "https://github.com/jasonkneen/pixelprovenance/blob/main/src/demo.tsx"

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_mount,node_toolbar,node_picker,node_crop,node_identity,node_signals,node_capture_image,node_site_user toneBlue
class node_decoder,node_pattern,node_spectral,node_demo_analysis toneAmber
class node_react_tags,node_cluso,node_demo toneMint
class node_package,node_transport,node_receiver,node_inbox,node_model_worker toneRose
class node_png_user toneIndigo
```

## Components

### Tagging and capture

- [Drop-in mount](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/mount.ts): `src/dropin/mount.ts`
- [Selection toolbar](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/toolbar.ts): `src/dropin/toolbar.ts`
- [Element picker](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/picker.ts): `src/dropin/picker.ts`
- [Crop gesture](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/crop.ts): `src/dropin/crop.ts`
- [Identity mapping](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/identity.ts): `src/dropin/identity.ts`
- [Visual signals](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/signal.ts): `src/dropin/signal.ts`
- [Screenshot capture](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/capture.ts): `src/dropin/capture.ts`

### Decode and analysis

- [PNG decoder](https://github.com/jasonkneen/pixelprovenance/blob/main/decoder/decode.ts): `decoder/decode.ts`
- [Pattern engine](https://github.com/jasonkneen/pixelprovenance/blob/main/src/pattern.ts): `src/pattern.ts`
- [Spectral analysis](https://github.com/jasonkneen/pixelprovenance/blob/main/src/spectral.ts): `src/spectral.ts`
- [Screenshot analysis](https://github.com/jasonkneen/pixelprovenance/blob/main/src/demo-analysis.ts): `src/demo-analysis.ts`

### Integrations

- [React tags](https://github.com/jasonkneen/pixelprovenance/blob/main/src/DevTag.tsx): `src/DevTag.tsx`
- [Cluso plugin](https://github.com/jasonkneen/pixelprovenance/blob/main/src/cluso/index.ts): `src/cluso/index.ts`
- [Interactive demo](https://github.com/jasonkneen/pixelprovenance/blob/main/src/demo.tsx): `src/demo.tsx`

### Package delivery

- [Selection package](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/package.ts): `src/dropin/package.ts`
- [Package transport](https://github.com/jasonkneen/pixelprovenance/blob/main/src/dropin/transport.ts): `src/dropin/transport.ts`
- [Reference receiver](https://github.com/jasonkneen/pixelprovenance/blob/main/server/receive.ts): `server/receive.ts`
- **Package files**

### Other components

- **Website user**
- **PNG and registry**
- **Model worker**

## Connections

- Website user → Selection toolbar: uses
- Drop-in mount → Selection toolbar: renders
- Drop-in mount → Visual signals: applies
- Selection toolbar → Drop-in mount: dispatches modes
- Drop-in mount → Element picker: starts selection
- Drop-in mount → Crop gesture: starts cropping
- Drop-in mount → Identity mapping: resolves identity
- Drop-in mount → Screenshot capture: captures region
- Drop-in mount → Screenshot analysis: verifies crop
- Drop-in mount → Selection package: creates package
- Drop-in mount → Package transport: delivers package
- Package transport → Reference receiver: POSTs package
- Reference receiver → Package files: writes files
- Reference receiver → Package transport: returns status
- PNG and registry → PNG decoder: provides PNG and registry
- PNG decoder → Pattern engine: generates patterns
- PNG decoder → Spectral analysis: detects carriers
- PNG decoder → PNG and registry: returns matches
- React tags → Pattern engine: generates signals
- Cluso plugin → Identity mapping: builds codebook
- Cluso plugin → Visual signals: applies signals
- Cluso plugin → Screenshot capture: captures screenshots
- Cluso plugin → Screenshot analysis: analyzes screenshots
- Interactive demo → React tags: renders tags
- Interactive demo → Screenshot analysis: analyzes crop
- Interactive demo → Model worker: demonstrates package use