# edvardgrishin27/frameproof architecture

> Architecture diagram of the GitHub repository edvardgrishin27/frameproof, 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/edvardgrishin27/frameproof
- Repository: https://github.com/edvardgrishin27/frameproof

## Overview

frameproof turns a video or link into a searchable, time-coded index with explicit coverage gaps, then exposes separate commands for text search, frame retrieval, and arithmetic verification of citations. The main path is fetch/probe, transcript and screen analysis, coverage-aware frame selection, extraction/OCR, and index creation. The README also documents Kinescope support and token budgeting. Some subsystem links rely on documented workflow or the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`frameproof/__main__.py`](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/__main__.py) (CLI commands), [`frameproof/index.py`](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/index.py) (Index and search), [`frameproof/fetch.py`](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/fetch.py) (Video fetch), [`frameproof/extract.py`](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/extract.py) (Frame extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Video ingestion"]
  node_fetch["Video fetch<br/>[fetch.py]"]
  node_kinescope["Kinescope loader<br/>[kinescope.py]"]
  node_probe["Video probe<br/>[probe.py]"]
end

subgraph group_analysis["Media analysis"]
  node_transcribe["Speech transcript<br/>[transcribe.py]"]
  node_analyze["Screen-change signal<br/>[analyze.py]"]
  node_select["Coverage selection<br/>[select.py]"]
  node_extract["Frame extraction<br/>[extract.py]"]
  node_ocr["Screen OCR<br/>[ocr.py]"]
end

subgraph group_indexing["Index and retrieval"]
  node_cli["CLI commands<br/>[__main__.py]"]
  node_index[("Index and search<br/>[index.py]")]
end

subgraph group_trust["Evidence and cost"]
  node_report["Coverage report<br/>[report.py]"]
  node_verify["Citation verification<br/>[verify.py]"]
  node_budget["Token budgeting<br/>[budget.py]"]
end

node_user(("User or agent"))
node_external_video["Video hosts"]

node_user -->|"runs commands"| node_cli
node_cli -->|"fetches media"| node_fetch
node_fetch -->|"routes Kinescope"| node_kinescope
node_fetch -.->|"downloads media"| node_external_video
node_cli -->|"probes video"| node_probe
node_cli -->|"loads subtitles"| node_transcribe
node_cli -->|"analyzes screen"| node_analyze
node_analyze -->|"uses video metadata"| node_probe
node_cli -->|"selects frames"| node_select
node_select -->|"uses change signal"| node_analyze
node_cli -->|"extracts selected frames"| node_extract
node_extract -->|"uses video metadata"| node_probe
node_extract -->|"sizes frames"| node_budget
node_cli -->|"recognizes screen text"| node_ocr
node_ocr -.->|"adds OCR text"| node_index
node_cli -->|"writes or searches index"| node_index
node_cli -->|"reports coverage"| node_report
node_report -->|"reports selection"| node_select
node_report -->|"estimates tokens"| node_budget
node_cli -->|"checks citations"| node_verify
node_verify -->|"reads indexed evidence"| node_index
node_user -->|"searches speech and OCR"| node_index
node_user -->|"requests specific frames"| node_cli

click node_cli "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/__main__.py"
click node_fetch "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/fetch.py"
click node_kinescope "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/kinescope.py"
click node_probe "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/probe.py"
click node_transcribe "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/transcribe.py"
click node_analyze "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/analyze.py"
click node_select "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/select.py"
click node_extract "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/extract.py"
click node_ocr "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/ocr.py"
click node_index "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/index.py"
click node_report "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/report.py"
click node_verify "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/verify.py"
click node_budget "https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/budget.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_fetch,node_kinescope,node_probe,node_user toneBlue
class node_transcribe,node_analyze,node_select,node_extract,node_ocr toneAmber
class node_cli,node_index toneMint
class node_report,node_verify,node_budget toneRose
class node_external_video toneIndigo
```

## Components

### Video ingestion

- [Video fetch](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/fetch.py): `frameproof/fetch.py`
- [Kinescope loader](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/kinescope.py): `frameproof/kinescope.py`
- [Video probe](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/probe.py): `frameproof/probe.py`

### Media analysis

- [Speech transcript](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/transcribe.py): `frameproof/transcribe.py`
- [Screen-change signal](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/analyze.py): `frameproof/analyze.py`
- [Coverage selection](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/select.py): `frameproof/select.py`
- [Frame extraction](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/extract.py): `frameproof/extract.py`
- [Screen OCR](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/ocr.py): `frameproof/ocr.py`

### Index and retrieval

- [CLI commands](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/__main__.py): `frameproof/__main__.py`
- [Index and search](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/index.py): `frameproof/index.py`

### Evidence and cost

- [Coverage report](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/report.py): `frameproof/report.py`
- [Citation verification](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/verify.py): `frameproof/verify.py`
- [Token budgeting](https://github.com/edvardgrishin27/frameproof/blob/main/frameproof/budget.py): `frameproof/budget.py`

### Other components

- **User or agent**
- **Video hosts**

## Connections

- User or agent → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Video fetch: fetches media (evidence: `frameproof/__main__.py`)
- Video fetch → Kinescope loader: routes Kinescope (evidence: `frameproof/fetch.py`)
- Video fetch → Video hosts: downloads media (evidence: `README.md`)
- CLI commands → Video probe: probes video (evidence: `frameproof/__main__.py`)
- CLI commands → Speech transcript: loads subtitles (evidence: `frameproof/__main__.py`)
- CLI commands → Screen-change signal: analyzes screen (evidence: `frameproof/__main__.py`)
- Screen-change signal → Video probe: uses video metadata (evidence: `frameproof/analyze.py`)
- CLI commands → Coverage selection: selects frames (evidence: `frameproof/__main__.py`)
- Coverage selection → Screen-change signal: uses change signal (evidence: `frameproof/select.py`)
- CLI commands → Frame extraction: extracts selected frames (evidence: `frameproof/__main__.py`)
- Frame extraction → Video probe: uses video metadata (evidence: `frameproof/extract.py`)
- Frame extraction → Token budgeting: sizes frames (evidence: `frameproof/extract.py`)
- CLI commands → Screen OCR: recognizes screen text (evidence: `frameproof/__main__.py`)
- Screen OCR → Index and search: adds OCR text (evidence: `frameproof/ocr.py`)
- CLI commands → Index and search: writes or searches index (evidence: `frameproof/__main__.py`)
- CLI commands → Coverage report: reports coverage (evidence: `frameproof/__main__.py`)
- Coverage report → Coverage selection: reports selection (evidence: `frameproof/report.py`)
- Coverage report → Token budgeting: estimates tokens (evidence: `frameproof/report.py`)
- CLI commands → Citation verification: checks citations (evidence: `frameproof/__main__.py`)
- Citation verification → Index and search: reads indexed evidence (evidence: `frameproof/verify.py`)
- User or agent → Index and search: searches speech and OCR (evidence: `README.md`)
- User or agent → CLI commands: requests specific frames (evidence: `README.md`)