# liyedanpdx/reddit-ai-trends architecture

> Architecture diagram of the GitHub repository liyedanpdx/reddit-ai-trends, 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/liyedanpdx/reddit-ai-trends
- Repository: https://github.com/liyedanpdx/reddit-ai-trends

## Overview

Reddit AI Trend Reports collects posts from configured communities, enriches them with comments and optional image, video, and web analysis, then generates dated English and Chinese trend reports. The central runtime entry point is `report_generation.py`; it coordinates collection, report processing, and persistence. The README also documents historical backfills, cached enrichment, and automatic latest-report links. Some collection-stage wiring and storage details are unsampled, so uncertain relationships are omitted or marked unverified.

Main entry points: [`report_generation.py`](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/report_generation.py) (Report Orchestrator), [`services/reddit_collection/collector.py`](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/collector.py) (Reddit Collector), [`services/reddit_collection/enrichers`](https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/enrichers) (Content Enrichers), [`services/llm_processing/report_processor.py`](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/report_processor.py) (Report Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Reddit Collection"]
  node_collector["Reddit Collector<br/>[collector.py]"]
  node_redditclient["Reddit API Client<br/>[client.py]"]
  node_fetchers["Post and Comment Fetchers"]
  node_models["Reddit Data Models<br/>[models.py]"]
  node_filters["Post and Comment Filters"]
end

subgraph group_analysis["Enrichment and Analysis"]
  node_enrichers["Content Enrichers"]
  node_imageanalysis["Image Analysis<br/>[image_analyzer.py]"]
end

subgraph group_reporting["Report Generation"]
  node_generation["Report Orchestrator"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_llmprocessor["Report Processor"]
  node_prompts["Prompt Loader<br/>[prompt_loader.py]"]
  node_factory["LLM Provider Factory<br/>[factory.py]"]
  node_groq["Groq Client<br/>[groq_client.py]"]
  node_openrouter["OpenRouter Client"]
end

subgraph group_persistence["Persistence and Backfill"]
  node_mongodb[("MongoDB<br/>[mongodb.py]")]
  node_reportfiles["Report Files"]
  node_backfill["Historical Backfill"]
end

node_operator(("Operator"))
node_scheduler(("Daily Trigger"))
node_llmservice{{"LLM APIs"}}
node_firecrawl{{"Firecrawl"}}
node_youtube{{"YouTube Transcripts"}}

node_operator -->|"runs"| node_generation
node_scheduler -->|"triggers"| node_generation
node_generation -->|"collects posts"| node_collector
node_generation -->|"generates reports"| node_llmprocessor
node_generation -->|"persists reports"| node_mongodb
node_generation -->|"reads settings"| node_config
node_collector -->|"uses API client"| node_redditclient
node_collector -->|"dispatches fetching"| node_fetchers
node_fetchers -->|"requests Reddit data"| node_redditclient
node_fetchers -->|"creates models"| node_models
node_collector -.->|"enriches posts"| node_enrichers
node_collector -.->|"filters posts"| node_filters
node_collector -->|"analyzes images"| node_imageanalysis
node_enrichers -.->|"caches enrichment"| node_mongodb
node_enrichers -.->|"scrapes pages"| node_firecrawl
node_enrichers -.->|"fetches transcripts"| node_youtube
node_enrichers -.->|"summarizes content"| node_llmservice
node_imageanalysis -.->|"analyzes images"| node_llmservice
node_llmprocessor -->|"creates client"| node_factory
node_llmprocessor -.->|"loads prompts"| node_prompts
node_factory -->|"selects provider"| node_groq
node_factory -->|"selects provider"| node_openrouter
node_groq -->|"generates text"| node_llmservice
node_openrouter -->|"generates text"| node_llmservice
node_llmprocessor -->|"writes reports"| node_reportfiles
node_backfill -->|"reads historical data"| node_mongodb
node_backfill -->|"regenerates reports"| node_generation

click node_generation "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/report_generation.py"
click node_config "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/config.py"
click node_collector "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/collector.py"
click node_redditclient "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/client.py"
click node_fetchers "https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/fetchers"
click node_models "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/models.py"
click node_filters "https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/filters"
click node_enrichers "https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/enrichers"
click node_imageanalysis "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/image_analyzer.py"
click node_llmprocessor "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/report_processor.py"
click node_prompts "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/core/prompt_loader.py"
click node_factory "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/core/factory.py"
click node_groq "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/clients/groq_client.py"
click node_openrouter "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/clients/openrouter_client.py"
click node_mongodb "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/database/mongodb.py"
click node_reportfiles "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/report_processor.py"
click node_backfill "https://github.com/liyedanpdx/reddit-ai-trends/blob/main/backfill/backfill_reports.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_collector,node_redditclient,node_fetchers,node_models,node_filters toneBlue
class node_enrichers,node_imageanalysis toneAmber
class node_generation,node_config,node_llmprocessor,node_prompts,node_factory,node_groq,node_openrouter,node_llmservice toneMint
class node_mongodb,node_reportfiles,node_backfill toneRose
class node_operator,node_scheduler,node_firecrawl,node_youtube toneIndigo
```

## Components

### Reddit Collection

- [Reddit Collector](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/collector.py): `services/reddit_collection/collector.py`
- [Reddit API Client](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/client.py): `services/reddit_collection/client.py`
- [Post and Comment Fetchers](https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/fetchers): `services/reddit_collection/fetchers`
- [Reddit Data Models](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/reddit_collection/models.py): `services/reddit_collection/models.py`
- [Post and Comment Filters](https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/filters): `services/reddit_collection/filters`

### Enrichment and Analysis

- [Content Enrichers](https://github.com/liyedanpdx/reddit-ai-trends/tree/main/services/reddit_collection/enrichers): `services/reddit_collection/enrichers`
- [Image Analysis](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/image_analyzer.py): `services/image_analyzer.py`

### Report Generation

- [Report Orchestrator](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/report_generation.py): `report_generation.py`
- [Runtime Configuration](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/config.py): `config.py`
- [Report Processor](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/report_processor.py): `services/llm_processing/report_processor.py`
- [Prompt Loader](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/core/prompt_loader.py): `services/llm_processing/core/prompt_loader.py`
- [LLM Provider Factory](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/core/factory.py): `services/llm_processing/core/factory.py`
- [Groq Client](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/clients/groq_client.py): `services/llm_processing/clients/groq_client.py`
- [OpenRouter Client](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/clients/openrouter_client.py): `services/llm_processing/clients/openrouter_client.py`

### Persistence and Backfill

- [MongoDB](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/database/mongodb.py): `database/mongodb.py`
- [Report Files](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/services/llm_processing/report_processor.py): `services/llm_processing/report_processor.py`
- [Historical Backfill](https://github.com/liyedanpdx/reddit-ai-trends/blob/main/backfill/backfill_reports.py): `backfill/backfill_reports.py`

### Other components

- **Operator**
- **Daily Trigger**
- **LLM APIs**
- **Firecrawl**
- **YouTube Transcripts**

## Connections

- Operator → Report Orchestrator: runs (evidence: `README.md`)
- Daily Trigger → Report Orchestrator: triggers (evidence: `report_generation.py`)
- Report Orchestrator → Reddit Collector: collects posts (evidence: `report_generation.py`)
- Report Orchestrator → Report Processor: generates reports (evidence: `report_generation.py`)
- Report Orchestrator → MongoDB: persists reports (evidence: `report_generation.py`)
- Report Orchestrator → Runtime Configuration: reads settings (evidence: `report_generation.py`)
- Reddit Collector → Reddit API Client: uses API client (evidence: `services/reddit_collection/collector.py`)
- Reddit Collector → Post and Comment Fetchers: dispatches fetching (evidence: `services/reddit_collection/collector.py`)
- Post and Comment Fetchers → Reddit API Client: requests Reddit data (evidence: `services/reddit_collection/fetchers/post_fetcher.py`)
- Post and Comment Fetchers → Reddit Data Models: creates models (evidence: `services/reddit_collection/fetchers/post_fetcher.py`)
- Reddit Collector → Content Enrichers: enriches posts (evidence: `services/reddit_collection/collector.py`)
- Reddit Collector → Post and Comment Filters: filters posts (evidence: `services/reddit_collection/collector.py`)
- Reddit Collector → Image Analysis: analyzes images (evidence: `services/reddit_collection/collector.py`)
- Content Enrichers → MongoDB: caches enrichment
- Content Enrichers → Firecrawl: scrapes pages
- Content Enrichers → YouTube Transcripts: fetches transcripts
- Content Enrichers → LLM APIs: summarizes content
- Image Analysis → LLM APIs: analyzes images
- Report Processor → LLM Provider Factory: creates client (evidence: `services/llm_processing/report_processor.py`)
- Report Processor → Prompt Loader: loads prompts
- LLM Provider Factory → Groq Client: selects provider (evidence: `services/llm_processing/core/factory.py`)
- LLM Provider Factory → OpenRouter Client: selects provider (evidence: `services/llm_processing/core/factory.py`)
- Groq Client → LLM APIs: generates text (evidence: `services/llm_processing/clients/groq_client.py`)
- OpenRouter Client → LLM APIs: generates text (evidence: `services/llm_processing/clients/openrouter_client.py`)
- Report Processor → Report Files: writes reports (evidence: `services/llm_processing/report_processor.py`)
- Historical Backfill → MongoDB: reads historical data (evidence: `backfill/backfill_reports.py`)
- Historical Backfill → Report Orchestrator: regenerates reports (evidence: `backfill/backfill_reports.py`)
