# bryanmatthewsimonson/xray architecture

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

- Interactive diagram: https://gitdiagram.com/bryanmatthewsimonson/xray
- Repository: https://github.com/bryanmatthewsimonson/xray

## Overview

X-Ray is a browser extension for capturing web sources, turning them into structured knowledge, reviewing and judging that knowledge, and publishing it to NOSTR. The main workflow starts with a user viewing or importing a source; the reader extracts it, then the user can structure claims and entities, run optional analyses, and publish signed events. Cases and the Network surface support broader investigation and discovery. The graph reflects README capabilities and indexed module references; unsampled implementation details and some runtime dispatch links are not inferred.

Main entry points: [`src/reader/index.js`](https://github.com/bryanmatthewsimonson/xray/blob/main/src/reader/index.js) (Reader capture), [`src/shared/entity-model.js`](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/entity-model.js) (Entity model), [`src/shared/event-builder.js`](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/event-builder.js) (Event builder), [`src/shared/claim-model.js`](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/claim-model.js) (Claim model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture"]
  node_reader["Reader capture<br/>[index.js]"]
  node_platform_handlers["Platform handlers"]
  node_pdf["PDF capture<br/>[pdf-engine.js]"]
  node_imports["Transcript &amp; batch imports<br/>[import-panel.js]"]
end

subgraph group_knowledge["Structure"]
  node_entities["Entity model<br/>[entity-model.js]"]
  node_claims["Claim model<br/>[claim-model.js]"]
  node_cases["Case workspace<br/>[case-membership.js]"]
  node_portal["Archive &amp; case portal<br/>[index.js]"]
end

subgraph group_analysis["Review"]
  node_audit["Epistemic audits"]
  node_forensic["Forensic findings<br/>[forensic-corpus.js]"]
  node_truth["Truth adjudication"]
  node_lens["Moral lens<br/>[lens-engine.js]"]
  node_llm["LLM assistance<br/>[llm-client.js]"]
end

subgraph group_publish["Publish &amp; Network"]
  node_events["Event builder<br/>[event-builder.js]"]
  node_network["Network client<br/>[index.js]"]
end

subgraph group_platform["Extension Core"]
  node_archive[("Local archive<br/>[archive-cache.js]")]
  node_crypto["NOSTR crypto<br/>[crypto.js]"]
  node_keys["Local key manager"]
  node_storage[("Extension storage<br/>[storage.js]")]
  node_background["Background service<br/>[index.js]"]
end

node_user(("User"))
node_source["Web sources"]
node_relays[("NOSTR relays")]
node_anthropic["Anthropic API"]

node_user -->|"views or imports"| node_source
node_source -->|"captured in"| node_reader
node_reader -->|"extracts via"| node_platform_handlers
node_reader -->|"routes PDFs"| node_pdf
node_user -->|"starts import"| node_imports
node_reader -->|"checks cache"| node_archive
node_reader -->|"tags entities"| node_entities
node_reader -->|"structures claims"| node_claims
node_reader -->|"runs audit"| node_audit
node_reader -->|"runs findings"| node_forensic
node_reader -->|"records verdicts"| node_truth
node_reader -->|"shows readings"| node_lens
node_reader -.->|"requests assistance"| node_llm
node_cases -->|"references entities"| node_entities
node_cases -->|"references claims"| node_claims
node_portal -->|"opens workspace"| node_cases
node_portal -->|"reads archive"| node_archive
node_llm -.->|"sends analysis"| node_anthropic
node_reader -->|"builds article events"| node_events
node_events -->|"resolves entity tags"| node_entities
node_background -->|"publishes events"| node_relays
node_events -.->|"hands off events"| node_background
node_keys -->|"signs locally"| node_crypto
node_entities -->|"loads entity keys"| node_keys
node_entities -->|"reads and writes"| node_storage
node_claims -->|"reads and writes"| node_storage
node_archive -->|"assembles article"| node_events
node_network -->|"fetches published work"| node_relays
node_network -->|"incorporates proposals"| node_claims

click node_reader "https://github.com/bryanmatthewsimonson/xray/blob/main/src/reader/index.js"
click node_platform_handlers "https://github.com/bryanmatthewsimonson/xray/tree/main/src/shared/platforms"
click node_pdf "https://github.com/bryanmatthewsimonson/xray/blob/main/src/reader/pdf-engine.js"
click node_imports "https://github.com/bryanmatthewsimonson/xray/blob/main/src/portal/import-panel.js"
click node_archive "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/archive-cache.js"
click node_entities "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/entity-model.js"
click node_claims "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/claim-model.js"
click node_cases "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/case-membership.js"
click node_events "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/event-builder.js"
click node_crypto "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/crypto.js"
click node_keys "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/local-key-manager.js"
click node_storage "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/storage.js"
click node_audit "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/audit/run-orchestrator.js"
click node_forensic "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/forensic-corpus.js"
click node_truth "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/truth-adjudication-model.js"
click node_lens "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/lens-engine.js"
click node_llm "https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/llm-client.js"
click node_portal "https://github.com/bryanmatthewsimonson/xray/blob/main/src/portal/index.js"
click node_network "https://github.com/bryanmatthewsimonson/xray/blob/main/src/network/index.js"
click node_background "https://github.com/bryanmatthewsimonson/xray/blob/main/src/background/index.js"

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_reader,node_platform_handlers,node_pdf,node_imports,node_user toneBlue
class node_entities,node_claims,node_cases,node_portal,node_relays toneAmber
class node_audit,node_forensic,node_truth,node_lens,node_llm,node_anthropic toneMint
class node_events,node_network toneRose
class node_archive,node_crypto,node_keys,node_storage,node_background,node_source toneIndigo
```

## Components

### Capture

- [Reader capture](https://github.com/bryanmatthewsimonson/xray/blob/main/src/reader/index.js): `src/reader/index.js`
- [Platform handlers](https://github.com/bryanmatthewsimonson/xray/tree/main/src/shared/platforms): `src/shared/platforms`
- [PDF capture](https://github.com/bryanmatthewsimonson/xray/blob/main/src/reader/pdf-engine.js): `src/reader/pdf-engine.js`
- [Transcript & batch imports](https://github.com/bryanmatthewsimonson/xray/blob/main/src/portal/import-panel.js): `src/portal/import-panel.js`

### Structure

- [Entity model](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/entity-model.js): `src/shared/entity-model.js`
- [Claim model](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/claim-model.js): `src/shared/claim-model.js`
- [Case workspace](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/case-membership.js): `src/shared/case-membership.js`
- [Archive & case portal](https://github.com/bryanmatthewsimonson/xray/blob/main/src/portal/index.js): `src/portal/index.js`

### Review

- [Epistemic audits](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/audit/run-orchestrator.js): `src/shared/audit/run-orchestrator.js`
- [Forensic findings](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/forensic-corpus.js): `src/shared/forensic-corpus.js`
- [Truth adjudication](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/truth-adjudication-model.js): `src/shared/truth-adjudication-model.js`
- [Moral lens](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/lens-engine.js): `src/shared/lens-engine.js`
- [LLM assistance](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/llm-client.js): `src/shared/llm-client.js`

### Publish & Network

- [Event builder](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/event-builder.js): `src/shared/event-builder.js`
- [Network client](https://github.com/bryanmatthewsimonson/xray/blob/main/src/network/index.js): `src/network/index.js`

### Extension Core

- [Local archive](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/archive-cache.js): `src/shared/archive-cache.js`
- [NOSTR crypto](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/crypto.js): `src/shared/crypto.js`
- [Local key manager](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/local-key-manager.js): `src/shared/local-key-manager.js`
- [Extension storage](https://github.com/bryanmatthewsimonson/xray/blob/main/src/shared/storage.js): `src/shared/storage.js`
- [Background service](https://github.com/bryanmatthewsimonson/xray/blob/main/src/background/index.js): `src/background/index.js`

### Other components

- **User**
- **Web sources**
- **NOSTR relays**
- **Anthropic API**

## Connections

- User → Web sources: views or imports (evidence: `README.md`)
- Web sources → Reader capture: captured in (evidence: `README.md`)
- Reader capture → Platform handlers: extracts via (evidence: `README.md`)
- Reader capture → PDF capture: routes PDFs (evidence: `README.md`)
- User → Transcript & batch imports: starts import (evidence: `README.md`)
- Reader capture → Local archive: checks cache (evidence: `src/shared/archive-cache.js`)
- Reader capture → Entity model: tags entities (evidence: `src/reader/index.js`)
- Reader capture → Claim model: structures claims (evidence: `src/reader/index.js`)
- Reader capture → Epistemic audits: runs audit (evidence: `README.md`)
- Reader capture → Forensic findings: runs findings (evidence: `README.md`)
- Reader capture → Truth adjudication: records verdicts (evidence: `README.md`)
- Reader capture → Moral lens: shows readings (evidence: `README.md`)
- Reader capture → LLM assistance: requests assistance (evidence: `README.md`)
- Case workspace → Entity model: references entities (evidence: `src/shared/case-membership.js`)
- Case workspace → Claim model: references claims (evidence: `src/shared/case-membership.js`)
- Archive & case portal → Case workspace: opens workspace (evidence: `src/portal/index.js`)
- Archive & case portal → Local archive: reads archive (evidence: `src/portal/index.js`)
- LLM assistance → Anthropic API: sends analysis (evidence: `README.md`)
- Reader capture → Event builder: builds article events (evidence: `src/reader/index.js`)
- Event builder → Entity model: resolves entity tags (evidence: `src/shared/event-builder.js`)
- Background service → NOSTR relays: publishes events (evidence: `README.md`)
- Event builder → Background service: hands off events (evidence: `src/background/index.js`)
- Local key manager → NOSTR crypto: signs locally (evidence: `src/shared/local-key-manager.js`)
- Entity model → Local key manager: loads entity keys (evidence: `src/shared/entity-model.js`)
- Entity model → Extension storage: reads and writes (evidence: `src/shared/entity-model.js`)
- Claim model → Extension storage: reads and writes (evidence: `src/shared/claim-model.js`)
- Local archive → Event builder: assembles article (evidence: `src/shared/archive-cache.js`)
- Network client → NOSTR relays: fetches published work (evidence: `README.md`)
- Network client → Claim model: incorporates proposals (evidence: `README.md`)
