# jxrxn/proof architecture

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

- Interactive diagram: https://gitdiagram.com/jxrxn/proof
- Repository: https://github.com/jxrxn/proof

## Overview

Proof is a browser-based Bitcoin timestamping app. Users hash text or files locally, request an OpenTimestamps proof, and save a standalone `.ots` file; verification re-hashes the original and checks that proof, optionally upgrading it with calendar data. A secondary, capability-limited ZIP package flow preserves the original alongside proof and metadata. The README documents calendar and Bitcoin-header network dependencies. Some implementation is unsampled, so links for those documented integrations rely on README evidence.

Main entry points: [`src/stamp.ts`](https://github.com/jxrxn/proof/blob/main/src/stamp.ts) (Create proof), [`src/verify.ts`](https://github.com/jxrxn/proof/blob/main/src/verify.ts) (Verify proof), [`src/main.ts`](https://github.com/jxrxn/proof/blob/main/src/main.ts) (App startup), [`src/lib/hashWorkerClient.ts`](https://github.com/jxrxn/proof/blob/main/src/lib/hashWorkerClient.ts) (Hash worker client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Stamp and verify"]
  node_stamp["Create proof<br/>[stamp.ts]"]
  node_verify["Verify proof<br/>[verify.ts]"]
  node_packagepolicy["Package capability"]
  node_proofpackage["ZIP package builder<br/>[proofPackage.ts]"]
end

subgraph group_hashing["Local hashing"]
  node_hashclient["Hash worker client"]
  node_hashworker["Hash worker"]
  node_hashshared["Chunked SHA-256<br/>[hashShared.ts]"]
  node_hashfallback["Streaming fallback<br/>[hash.ts]"]
  node_hashprotocol["Worker protocol"]
end

subgraph group_proofs["Proof services"]
  node_otsadapter["OTS adapter<br/>[ots.ts]"]
  node_otsclient["OpenTimestamps client"]
  node_calendars["Calendar servers"]
  node_bitcoinheaders["Bitcoin header source"]
end

subgraph group_interface["User interface"]
  node_app["App startup<br/>[main.ts]"]
  node_dom["DOM helpers<br/>[dom.ts]"]
  node_operationui["Operation status UI<br/>[operationUi.ts]"]
  node_icons["Brand icons<br/>[icons.ts]"]
end

node_user(("User"))
node_download(("Local proof download"))

node_user -->|"uses"| node_app
node_app -->|"initializes"| node_stamp
node_app -->|"initializes"| node_verify
node_app -->|"exposes test hook"| node_hashclient
node_app -->|"embeds logo"| node_icons
node_stamp -->|"hashes via worker"| node_hashclient
node_verify -->|"hashes via worker"| node_hashclient
node_stamp -->|"falls back to"| node_hashfallback
node_verify -->|"falls back to"| node_hashfallback
node_hashclient -->|"dispatches job"| node_hashworker
node_hashclient -->|"uses messages"| node_hashprotocol
node_hashworker -->|"handles messages"| node_hashprotocol
node_hashworker -->|"hashes chunks"| node_hashshared
node_hashfallback -->|"uses chunking"| node_hashshared
node_stamp -->|"creates digest proof"| node_otsadapter
node_stamp -->|"stamps proof"| node_otsclient
node_verify -->|"upgrades and verifies"| node_otsclient
node_otsadapter -->|"creates detached proof"| node_otsclient
node_otsadapter -->|"probes endpoints"| node_calendars
node_otsclient -->|"submits digest"| node_calendars
node_otsclient -->|"checks anchoring"| node_bitcoinheaders
node_stamp -->|"checks availability"| node_packagepolicy
node_verify -->|"checks availability"| node_packagepolicy
node_stamp -->|"builds optional ZIP"| node_proofpackage
node_verify -->|"builds optional ZIP"| node_proofpackage
node_stamp -->|"updates interface"| node_dom
node_verify -->|"renders verdict"| node_dom
node_stamp -->|"reports progress"| node_operationui
node_verify -->|"reports progress"| node_operationui
node_stamp -->|"offers proof file"| node_download
node_proofpackage -->|"offers ZIP"| node_download

click node_app "https://github.com/jxrxn/proof/blob/main/src/main.ts"
click node_stamp "https://github.com/jxrxn/proof/blob/main/src/stamp.ts"
click node_verify "https://github.com/jxrxn/proof/blob/main/src/verify.ts"
click node_hashclient "https://github.com/jxrxn/proof/blob/main/src/lib/hashWorkerClient.ts"
click node_hashworker "https://github.com/jxrxn/proof/blob/main/src/workers/hashWorkerRuntime.ts"
click node_hashshared "https://github.com/jxrxn/proof/blob/main/src/lib/hashShared.ts"
click node_hashfallback "https://github.com/jxrxn/proof/blob/main/src/lib/hash.ts"
click node_hashprotocol "https://github.com/jxrxn/proof/blob/main/src/lib/hashWorkerProtocol.ts"
click node_otsadapter "https://github.com/jxrxn/proof/blob/main/src/lib/ots.ts"
click node_packagepolicy "https://github.com/jxrxn/proof/blob/main/src/lib/packageCapability.ts"
click node_proofpackage "https://github.com/jxrxn/proof/blob/main/src/lib/proofPackage.ts"
click node_dom "https://github.com/jxrxn/proof/blob/main/src/lib/dom.ts"
click node_operationui "https://github.com/jxrxn/proof/blob/main/src/lib/operationUi.ts"
click node_icons "https://github.com/jxrxn/proof/blob/main/src/icons/icons.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_stamp,node_verify,node_packagepolicy,node_proofpackage,node_user toneBlue
class node_hashclient,node_hashworker,node_hashshared,node_hashfallback,node_hashprotocol toneAmber
class node_otsadapter,node_otsclient,node_calendars,node_bitcoinheaders toneMint
class node_app,node_dom,node_operationui,node_icons toneRose
class node_download toneIndigo
```

## Components

### Stamp and verify

- [Create proof](https://github.com/jxrxn/proof/blob/main/src/stamp.ts): `src/stamp.ts`
- [Verify proof](https://github.com/jxrxn/proof/blob/main/src/verify.ts): `src/verify.ts`
- [Package capability](https://github.com/jxrxn/proof/blob/main/src/lib/packageCapability.ts): `src/lib/packageCapability.ts`
- [ZIP package builder](https://github.com/jxrxn/proof/blob/main/src/lib/proofPackage.ts): `src/lib/proofPackage.ts`

### Local hashing

- [Hash worker client](https://github.com/jxrxn/proof/blob/main/src/lib/hashWorkerClient.ts): `src/lib/hashWorkerClient.ts`
- [Hash worker](https://github.com/jxrxn/proof/blob/main/src/workers/hashWorkerRuntime.ts): `src/workers/hashWorkerRuntime.ts`
- [Chunked SHA-256](https://github.com/jxrxn/proof/blob/main/src/lib/hashShared.ts): `src/lib/hashShared.ts`
- [Streaming fallback](https://github.com/jxrxn/proof/blob/main/src/lib/hash.ts): `src/lib/hash.ts`
- [Worker protocol](https://github.com/jxrxn/proof/blob/main/src/lib/hashWorkerProtocol.ts): `src/lib/hashWorkerProtocol.ts`

### Proof services

- [OTS adapter](https://github.com/jxrxn/proof/blob/main/src/lib/ots.ts): `src/lib/ots.ts`
- **OpenTimestamps client**
- **Calendar servers**
- **Bitcoin header source**

### User interface

- [App startup](https://github.com/jxrxn/proof/blob/main/src/main.ts): `src/main.ts`
- [DOM helpers](https://github.com/jxrxn/proof/blob/main/src/lib/dom.ts): `src/lib/dom.ts`
- [Operation status UI](https://github.com/jxrxn/proof/blob/main/src/lib/operationUi.ts): `src/lib/operationUi.ts`
- [Brand icons](https://github.com/jxrxn/proof/blob/main/src/icons/icons.ts): `src/icons/icons.ts`

### Other components

- **User**
- **Local proof download**

## Connections

- User → App startup: uses (evidence: `README.md`)
- App startup → Create proof: initializes (evidence: `src/main.ts`)
- App startup → Verify proof: initializes (evidence: `src/main.ts`)
- App startup → Hash worker client: exposes test hook (evidence: `src/main.ts`)
- App startup → Brand icons: embeds logo (evidence: `src/main.ts`)
- Create proof → Hash worker client: hashes via worker (evidence: `src/stamp.ts`)
- Verify proof → Hash worker client: hashes via worker (evidence: `src/verify.ts`)
- Create proof → Streaming fallback: falls back to (evidence: `src/stamp.ts`)
- Verify proof → Streaming fallback: falls back to (evidence: `src/verify.ts`)
- Hash worker client → Hash worker: dispatches job (evidence: `src/lib/hashWorkerClient.ts`)
- Hash worker client → Worker protocol: uses messages (evidence: `src/lib/hashWorkerClient.ts`)
- Hash worker → Worker protocol: handles messages (evidence: `src/workers/hashWorkerRuntime.ts`)
- Hash worker → Chunked SHA-256: hashes chunks (evidence: `src/workers/hashWorkerRuntime.ts`)
- Streaming fallback → Chunked SHA-256: uses chunking (evidence: `src/lib/hash.ts`)
- Create proof → OTS adapter: creates digest proof (evidence: `src/stamp.ts`)
- Create proof → OpenTimestamps client: stamps proof (evidence: `src/stamp.ts`)
- Verify proof → OpenTimestamps client: upgrades and verifies (evidence: `src/verify.ts`)
- OTS adapter → OpenTimestamps client: creates detached proof (evidence: `src/lib/ots.ts`)
- OTS adapter → Calendar servers: probes endpoints (evidence: `src/lib/ots.ts`)
- OpenTimestamps client → Calendar servers: submits digest (evidence: `README.md`)
- OpenTimestamps client → Bitcoin header source: checks anchoring (evidence: `README.md`)
- Create proof → Package capability: checks availability (evidence: `src/stamp.ts`)
- Verify proof → Package capability: checks availability (evidence: `src/verify.ts`)
- Create proof → ZIP package builder: builds optional ZIP (evidence: `src/stamp.ts`)
- Verify proof → ZIP package builder: builds optional ZIP (evidence: `src/verify.ts`)
- Create proof → DOM helpers: updates interface (evidence: `src/stamp.ts`)
- Verify proof → DOM helpers: renders verdict (evidence: `src/verify.ts`)
- Create proof → Operation status UI: reports progress (evidence: `src/stamp.ts`)
- Verify proof → Operation status UI: reports progress (evidence: `src/verify.ts`)
- Create proof → Local proof download: offers proof file (evidence: `README.md`)
- ZIP package builder → Local proof download: offers ZIP (evidence: `README.md`)