# jeongujeong117-byte/ai-raider architecture

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

- Interactive diagram: https://gitdiagram.com/jeongujeong117-byte/ai-raider
- Repository: https://github.com/jeongujeong117-byte/ai-raider

## Overview

AI Raider is a local social-media research collector with a browser-based management UI. Its main workflow is selecting accounts and a date range, collecting Instagram/X posts, persisting posts and reactions (and optionally media), then browsing or exporting results. Separate branches collect public GitHub repositories and configured web sources. Downloaded media can enter a durable local OCR/transcription queue. The supplied source excerpts show the main runner and processing behavior; some UI routes and storage details are described only in the README, so those links cite it.

Main entry points: [`raider.py`](https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py) (Local HTTP server), [`source_agents.py`](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py) (Source workers), [`source_tools.py`](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_tools.py) (Public fetch tools), [`github_agent.py`](https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py) (GitHub collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Local interface"]
  node_main_ui["Collection UI<br/>[index.html]"]
  node_sources_ui["Sources UI<br/>[sources.html]"]
  node_github_ui["GitHub UI<br/>[github.html]"]
  node_http_server["Local HTTP server<br/>[raider.py]"]
end

subgraph group_social["Social collection"]
  node_registry["Account registry<br/>[source_manager.py]"]
  node_runner["Collection runner<br/>[raider.py]"]
  node_instagram["Instagram adapter<br/>[raider.py]"]
  node_x_adapter["X adapter<br/>[raider.py]"]
  node_media_download["Media downloader<br/>[media_store.py]"]
end

subgraph group_sources["Other sources"]
  node_github_agent["GitHub collector<br/>[github_agent.py]"]
  node_public_github["GitHub API client<br/>[github_agent.py]"]
  node_source_workers["Source workers<br/>[source_agents.py]"]
  node_youtube["YouTube extractor<br/>[source_agents.py]"]
  node_news["News extractor<br/>[source_agents.py]"]
  node_gallery["Gallery extractor<br/>[source_agents.py]"]
  node_huggingface["Hugging Face extractor<br/>[source_agents.py]"]
  node_source_tools["Public fetch tools<br/>[source_tools.py]"]
end

subgraph group_storage["Persistence"]
  node_post_store[("Posts and runs<br/>[raider.py]")]
  node_github_store[("GitHub records<br/>[github_agent.py]")]
  node_source_store[("Source records<br/>[source_agents.py]")]
  node_media_files[("Media files<br/>[media_store.py]")]
end

subgraph group_processing["Local extraction"]
  node_processor["Processing queue<br/>[post_processing.py]"]
  node_engines["OCR and transcription<br/>[post_processing.py]"]
end

node_user(("Researcher"))
node_social_platforms{{"Instagram and X"}}
node_github_service{{"GitHub"}}
node_web_sources{{"Public web sources"}}
node_local_models{{"Local OCR and speech models"}}

node_user -->|"selects range"| node_main_ui
node_user -->|"configures sources"| node_sources_ui
node_user -->|"starts collection"| node_github_ui
node_main_ui -->|"sends requests"| node_http_server
node_sources_ui -->|"sends requests"| node_http_server
node_github_ui -->|"sends requests"| node_http_server
node_http_server -->|"manages accounts"| node_registry
node_http_server -->|"starts collection"| node_runner
node_runner -->|"collects posts"| node_instagram
node_runner -->|"collects posts"| node_x_adapter
node_social_platforms -->|"provides posts"| node_instagram
node_social_platforms -->|"provides posts"| node_x_adapter
node_runner -->|"downloads media"| node_media_download
node_runner -->|"saves posts"| node_post_store
node_media_download -->|"writes files"| node_media_files
node_runner -->|"queues posts"| node_processor
node_processor -->|"routes attachments"| node_engines
node_engines -->|"uses models"| node_local_models
node_http_server -->|"queries and exports"| node_post_store
node_http_server -->|"reports status"| node_processor
node_http_server -->|"dispatches requests"| node_github_agent
node_github_agent -->|"searches repositories"| node_public_github
node_public_github -->|"uses API"| node_github_service
node_github_agent -->|"saves records"| node_github_store
node_http_server -->|"dispatches requests"| node_source_workers
node_source_workers -->|"selects extractor"| node_youtube
node_source_workers -->|"selects extractor"| node_news
node_source_workers -->|"selects extractor"| node_gallery
node_source_workers -->|"selects extractor"| node_huggingface
node_youtube -.->|"fetches public content"| node_source_tools
node_news -.->|"fetches public content"| node_source_tools
node_gallery -.->|"fetches public content"| node_source_tools
node_source_workers -->|"saves results"| node_source_store
node_source_tools -->|"fetches pages"| node_web_sources

click node_main_ui "https://github.com/jeongujeong117-byte/ai-raider/blob/master/web/index.html"
click node_sources_ui "https://github.com/jeongujeong117-byte/ai-raider/blob/master/web/sources.html"
click node_github_ui "https://github.com/jeongujeong117-byte/ai-raider/blob/master/web/github.html"
click node_http_server "https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py"
click node_registry "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_manager.py"
click node_runner "https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py"
click node_instagram "https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py"
click node_x_adapter "https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py"
click node_media_download "https://github.com/jeongujeong117-byte/ai-raider/blob/master/media_store.py"
click node_github_agent "https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py"
click node_public_github "https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py"
click node_source_workers "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py"
click node_youtube "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py"
click node_news "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py"
click node_gallery "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py"
click node_huggingface "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py"
click node_source_tools "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_tools.py"
click node_post_store "https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py"
click node_github_store "https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py"
click node_source_store "https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py"
click node_media_files "https://github.com/jeongujeong117-byte/ai-raider/blob/master/media_store.py"
click node_processor "https://github.com/jeongujeong117-byte/ai-raider/blob/master/post_processing.py"
click node_engines "https://github.com/jeongujeong117-byte/ai-raider/blob/master/post_processing.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_main_ui,node_sources_ui,node_github_ui,node_http_server toneBlue
class node_registry,node_runner,node_instagram,node_x_adapter,node_media_download toneAmber
class node_github_agent,node_public_github,node_source_workers,node_youtube,node_news,node_gallery,node_huggingface,node_source_tools toneMint
class node_post_store,node_github_store,node_source_store,node_media_files toneRose
class node_processor,node_engines,node_user,node_social_platforms,node_github_service,node_web_sources,node_local_models toneIndigo
```

## Components

### Local interface

- [Collection UI](https://github.com/jeongujeong117-byte/ai-raider/blob/master/web/index.html): `web/index.html`
- [Sources UI](https://github.com/jeongujeong117-byte/ai-raider/blob/master/web/sources.html): `web/sources.html`
- [GitHub UI](https://github.com/jeongujeong117-byte/ai-raider/blob/master/web/github.html): `web/github.html`
- [Local HTTP server](https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py): `raider.py`

### Social collection

- [Account registry](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_manager.py): `source_manager.py`
- [Collection runner](https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py): `raider.py`
- [Instagram adapter](https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py): `raider.py`
- [X adapter](https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py): `raider.py`
- [Media downloader](https://github.com/jeongujeong117-byte/ai-raider/blob/master/media_store.py): `media_store.py`

### Other sources

- [GitHub collector](https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py): `github_agent.py`
- [GitHub API client](https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py): `github_agent.py`
- [Source workers](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py): `source_agents.py`
- [YouTube extractor](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py): `source_agents.py`
- [News extractor](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py): `source_agents.py`
- [Gallery extractor](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py): `source_agents.py`
- [Hugging Face extractor](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py): `source_agents.py`
- [Public fetch tools](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_tools.py): `source_tools.py`

### Persistence

- [Posts and runs](https://github.com/jeongujeong117-byte/ai-raider/blob/master/raider.py): `raider.py`
- [GitHub records](https://github.com/jeongujeong117-byte/ai-raider/blob/master/github_agent.py): `github_agent.py`
- [Source records](https://github.com/jeongujeong117-byte/ai-raider/blob/master/source_agents.py): `source_agents.py`
- [Media files](https://github.com/jeongujeong117-byte/ai-raider/blob/master/media_store.py): `media_store.py`

### Local extraction

- [Processing queue](https://github.com/jeongujeong117-byte/ai-raider/blob/master/post_processing.py): `post_processing.py`
- [OCR and transcription](https://github.com/jeongujeong117-byte/ai-raider/blob/master/post_processing.py): `post_processing.py`

### Other components

- **Researcher**
- **Instagram and X**
- **GitHub**
- **Public web sources**
- **Local OCR and speech models**

## Connections

- Researcher → Collection UI: selects range (evidence: `README.md`)
- Researcher → Sources UI: configures sources (evidence: `README.md`)
- Researcher → GitHub UI: starts collection (evidence: `README.md`)
- Collection UI → Local HTTP server: sends requests (evidence: `README.md`)
- Sources UI → Local HTTP server: sends requests (evidence: `README.md`)
- GitHub UI → Local HTTP server: sends requests (evidence: `README.md`)
- Local HTTP server → Account registry: manages accounts (evidence: `README.md`)
- Local HTTP server → Collection runner: starts collection (evidence: `raider.py`)
- Collection runner → Instagram adapter: collects posts (evidence: `raider.py`)
- Collection runner → X adapter: collects posts (evidence: `raider.py`)
- Instagram and X → Instagram adapter: provides posts (evidence: `README.md`)
- Instagram and X → X adapter: provides posts (evidence: `README.md`)
- Collection runner → Media downloader: downloads media (evidence: `raider.py`)
- Collection runner → Posts and runs: saves posts (evidence: `raider.py`)
- Media downloader → Media files: writes files (evidence: `media_store.py`)
- Collection runner → Processing queue: queues posts (evidence: `raider.py`)
- Processing queue → OCR and transcription: routes attachments (evidence: `post_processing.py`)
- OCR and transcription → Local OCR and speech models: uses models (evidence: `README.md`)
- Local HTTP server → Posts and runs: queries and exports (evidence: `raider.py`)
- Local HTTP server → Processing queue: reports status (evidence: `raider.py`)
- Local HTTP server → GitHub collector: dispatches requests (evidence: `raider.py`)
- GitHub collector → GitHub API client: searches repositories (evidence: `github_agent.py`)
- GitHub API client → GitHub: uses API (evidence: `README.md`)
- GitHub collector → GitHub records: saves records (evidence: `github_agent.py`)
- Local HTTP server → Source workers: dispatches requests (evidence: `raider.py`)
- Source workers → YouTube extractor: selects extractor (evidence: `source_agents.py`)
- Source workers → News extractor: selects extractor (evidence: `source_agents.py`)
- Source workers → Gallery extractor: selects extractor (evidence: `source_agents.py`)
- Source workers → Hugging Face extractor: selects extractor (evidence: `source_agents.py`)
- YouTube extractor → Public fetch tools: fetches public content (evidence: `source_agents.py`)
- News extractor → Public fetch tools: fetches public content (evidence: `source_agents.py`)
- Gallery extractor → Public fetch tools: fetches public content (evidence: `source_agents.py`)
- Source workers → Source records: saves results (evidence: `source_agents.py`)
- Public fetch tools → Public web sources: fetches pages (evidence: `source_tools.py`)