# pffantom1290/full-video-finder architecture

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

- Interactive diagram: https://gitdiagram.com/pffantom1290/full-video-finder
- Repository: https://github.com/pffantom1290/full-video-finder

## Overview

Full Video Finder takes a TikTok clip URL and searches for its longer source by identifying the work from clip content, then finding and verifying candidate videos. The README documents the staged workflow; sampled source confirms the pipeline orchestration and several internal dependencies. Some provider and API wiring is unsampled, so uncertain connections are omitted or shown as unverified.

Main entry points: [`backend/app/pipeline.py`](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/pipeline.py) (Search pipeline), [`backend/app/signals.py`](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/signals.py) (Signal collection), [`frontend/app.js`](https://github.com/pffantom1290/full-video-finder/blob/main/frontend/app.js) (Web interface), [`backend/app/main.py`](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_frontend["Web interface<br/>[app.js]"]
  node_api["HTTP API<br/>[main.py]"]
  node_pipeline["Search pipeline<br/>[pipeline.py]"]
end

subgraph group_analysis["Clip analysis"]
  node_tiktok["Clip resolver<br/>[tiktok.py]"]
  node_media["Frame extraction<br/>[media.py]"]
  node_signals["Signal collection<br/>[signals.py]"]
  node_asr["Speech recognition<br/>[asr.py]"]
  node_vision["Visual recognition<br/>[vision.py]"]
end

subgraph group_discovery["Search and identification"]
  node_provider_registry["Provider registry<br/>[__init__.py]"]
  node_providers["Search providers"]
  node_websearch["Web search<br/>[websearch.py]"]
  node_engines["Search engines<br/>[engines.py]"]
  node_identify["Work identification<br/>[identify.py]"]
  node_catalog["Work catalog<br/>[catalog.py]"]
  node_translate["Query translation<br/>[translate.py]"]
end

subgraph group_confirmation["Ranking and proof"]
  node_scoring["Candidate ranking<br/>[scoring.py]"]
  node_verify["Frame verification<br/>[verify.py]"]
end

subgraph group_shared["Shared internals"]
  node_models["Shared data models<br/>[models.py]"]
  node_textstats["Text statistics<br/>[textstats.py]"]
  node_imghash["Image hashing<br/>[imghash.py]"]
  node_httpclient["HTTP client and cache<br/>[httpx_client.py]"]
end

node_user(("Clip seeker"))
node_external_services["External search services"]

node_user -->|"submits clip"| node_frontend
node_frontend -.->|"requests search"| node_api
node_api -->|"runs search"| node_pipeline
node_pipeline -->|"resolves clip"| node_tiktok
node_pipeline -->|"collects signals"| node_signals
node_signals -->|"extracts frames"| node_media
node_signals -->|"transcribes audio"| node_asr
node_signals -->|"analyzes frames"| node_vision
node_pipeline -->|"gets providers"| node_provider_registry
node_provider_registry -->|"registers providers"| node_providers
node_pipeline -->|"identifies work"| node_identify
node_identify -->|"checks hypothesis"| node_catalog
node_pipeline -->|"expands queries"| node_translate
node_websearch -->|"searches queries"| node_engines
node_engines -->|"queries search APIs"| node_external_services
node_pipeline -->|"ranks candidates"| node_scoring
node_pipeline -->|"verifies frames"| node_verify
node_scoring -->|"weights terms"| node_textstats
node_media -->|"hashes frames"| node_imghash
node_verify -->|"compares hashes"| node_imghash
node_pipeline -->|"passes search data"| node_models
node_httpclient -.->|"sends HTTP"| node_external_services

click node_frontend "https://github.com/pffantom1290/full-video-finder/blob/main/frontend/app.js"
click node_api "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/main.py"
click node_pipeline "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/pipeline.py"
click node_tiktok "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/tiktok.py"
click node_media "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/media.py"
click node_signals "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/signals.py"
click node_asr "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/asr.py"
click node_vision "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/vision.py"
click node_provider_registry "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/providers/__init__.py"
click node_providers "https://github.com/pffantom1290/full-video-finder/tree/main/backend/app/providers"
click node_websearch "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/providers/websearch.py"
click node_engines "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/engines.py"
click node_identify "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/identify.py"
click node_catalog "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/catalog.py"
click node_translate "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/translate.py"
click node_scoring "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/scoring.py"
click node_verify "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/verify.py"
click node_models "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/models.py"
click node_textstats "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/textstats.py"
click node_imghash "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/imghash.py"
click node_httpclient "https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/httpx_client.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_frontend,node_api,node_pipeline toneBlue
class node_tiktok,node_media,node_signals,node_asr,node_vision toneAmber
class node_provider_registry,node_providers,node_websearch,node_engines,node_identify,node_catalog,node_translate toneMint
class node_scoring,node_verify toneRose
class node_models,node_textstats,node_imghash,node_httpclient,node_user,node_external_services toneIndigo
```

## Components

### Application entry

- [Web interface](https://github.com/pffantom1290/full-video-finder/blob/main/frontend/app.js): `frontend/app.js`
- [HTTP API](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/main.py): `backend/app/main.py`
- [Search pipeline](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/pipeline.py): `backend/app/pipeline.py`

### Clip analysis

- [Clip resolver](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/tiktok.py): `backend/app/tiktok.py`
- [Frame extraction](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/media.py): `backend/app/media.py`
- [Signal collection](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/signals.py): `backend/app/signals.py`
- [Speech recognition](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/asr.py): `backend/app/asr.py`
- [Visual recognition](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/vision.py): `backend/app/vision.py`

### Search and identification

- [Provider registry](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/providers/__init__.py): `backend/app/providers/__init__.py`
- [Search providers](https://github.com/pffantom1290/full-video-finder/tree/main/backend/app/providers): `backend/app/providers`
- [Web search](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/providers/websearch.py): `backend/app/providers/websearch.py`
- [Search engines](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/engines.py): `backend/app/engines.py`
- [Work identification](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/identify.py): `backend/app/identify.py`
- [Work catalog](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/catalog.py): `backend/app/catalog.py`
- [Query translation](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/translate.py): `backend/app/translate.py`

### Ranking and proof

- [Candidate ranking](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/scoring.py): `backend/app/scoring.py`
- [Frame verification](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/verify.py): `backend/app/verify.py`

### Shared internals

- [Shared data models](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/models.py): `backend/app/models.py`
- [Text statistics](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/textstats.py): `backend/app/textstats.py`
- [Image hashing](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/imghash.py): `backend/app/imghash.py`
- [HTTP client and cache](https://github.com/pffantom1290/full-video-finder/blob/main/backend/app/httpx_client.py): `backend/app/httpx_client.py`

### Other components

- **Clip seeker**
- **External search services**

## Connections

- Clip seeker → Web interface: submits clip (evidence: `README.md`)
- Web interface → HTTP API: requests search
- HTTP API → Search pipeline: runs search (evidence: `backend/app/main.py`)
- Search pipeline → Clip resolver: resolves clip (evidence: `README.md`)
- Search pipeline → Signal collection: collects signals (evidence: `backend/app/pipeline.py`)
- Signal collection → Frame extraction: extracts frames (evidence: `backend/app/signals.py`)
- Signal collection → Speech recognition: transcribes audio (evidence: `backend/app/signals.py`)
- Signal collection → Visual recognition: analyzes frames (evidence: `backend/app/signals.py`)
- Search pipeline → Provider registry: gets providers (evidence: `backend/app/pipeline.py`)
- Provider registry → Search providers: registers providers (evidence: `backend/app/providers/__init__.py`)
- Search pipeline → Work identification: identifies work (evidence: `README.md`)
- Work identification → Work catalog: checks hypothesis (evidence: `backend/app/identify.py`)
- Search pipeline → Query translation: expands queries (evidence: `backend/app/pipeline.py`)
- Web search → Search engines: searches queries (evidence: `backend/app/providers/websearch.py`)
- Search engines → External search services: queries search APIs (evidence: `backend/app/engines.py`)
- Search pipeline → Candidate ranking: ranks candidates (evidence: `README.md`)
- Search pipeline → Frame verification: verifies frames (evidence: `backend/app/pipeline.py`)
- Candidate ranking → Text statistics: weights terms (evidence: `README.md`)
- Frame extraction → Image hashing: hashes frames (evidence: `backend/app/media.py`)
- Frame verification → Image hashing: compares hashes (evidence: `backend/app/verify.py`)
- Search pipeline → Shared data models: passes search data (evidence: `backend/app/pipeline.py`)
- HTTP client and cache → External search services: sends HTTP
