# sumitkr0843/trend_finder_backend architecture

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

- Interactive diagram: https://gitdiagram.com/sumitkr0843/trend_finder_backend
- Repository: https://github.com/sumitkr0843/trend_finder_backend

## Overview

Trend Finder gathers social content for a niche, ranks it, and mines it into a content brief; it also supports AI draft generation and review. The API is the principal user-facing workflow, with a separate CLI that saves results and can render an HTML dashboard. Platform collectors normalize results from external services, while ranking and analysis form the core processing layer. Source excerpts support the API/CLI call paths and integrations; unsampled implementation details are not inferred.

Main entry points: [`api/main.py`](https://github.com/sumitkr0843/trend_finder_backend/blob/main/api/main.py) (Search API), [`main.py`](https://github.com/sumitkr0843/trend_finder_backend/blob/main/main.py) (CLI workflow), [`config/config.py`](https://github.com/sumitkr0843/trend_finder_backend/blob/main/config/config.py) (Credentials config), [`scripts/analyzer.py`](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py) (Trend mining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_api["Search API<br/>[main.py]"]
  node_cli["CLI workflow<br/>[main.py]"]
  node_config["Credentials config<br/>[config.py]"]
end

subgraph group_collect["Social collection"]
  node_reddit["Reddit search<br/>[reddit.py]"]
  node_youtube["YouTube search<br/>[youtube.py]"]
  node_tiktok["TikTok search<br/>[tiktok.py]"]
  node_instagram["Instagram search<br/>[instagram.py]"]
  node_xsearch["X search<br/>[x.py]"]
end

subgraph group_process["Analysis and ranking"]
  node_ranking["Engagement ranking<br/>[ranking.py]"]
  node_analyzer["Trend mining<br/>[analyzer.py]"]
end

subgraph group_output["Content and reporting"]
  node_generation["Draft generation<br/>[analyzer.py]"]
  node_review["Draft review<br/>[analyzer.py]"]
  node_render["HTML dashboard<br/>[render.py]"]
end

node_user(("User"))
node_apify{{"Apify actors"}}
node_firecrawl{{"Firecrawl search"}}
node_llm{{"OpenAI service"}}

node_user -->|"submits requests"| node_api
node_user -->|"enters niche"| node_cli
node_api -->|"dispatches search"| node_reddit
node_api -->|"dispatches search"| node_youtube
node_api -->|"dispatches search"| node_tiktok
node_api -->|"dispatches search"| node_instagram
node_api -->|"dispatches search"| node_xsearch
node_cli -->|"dispatches search"| node_reddit
node_cli -->|"dispatches search"| node_youtube
node_cli -->|"dispatches search"| node_tiktok
node_cli -->|"dispatches search"| node_instagram
node_reddit -->|"reads key"| node_config
node_youtube -->|"reads token"| node_config
node_tiktok -->|"reads token"| node_config
node_instagram -->|"reads token"| node_config
node_xsearch -->|"reads token"| node_config
node_analyzer -->|"reads model settings"| node_config
node_reddit -->|"searches web"| node_firecrawl
node_youtube -->|"runs actor"| node_apify
node_tiktok -->|"runs actor"| node_apify
node_instagram -->|"runs actors"| node_apify
node_xsearch -->|"runs actor"| node_apify
node_api -->|"ranks results"| node_ranking
node_api -->|"mines trends"| node_analyzer
node_cli -->|"ranks results"| node_ranking
node_cli -->|"mines trends"| node_analyzer
node_cli -->|"renders dashboard"| node_render
node_analyzer -->|"requests completion"| node_llm
node_api -->|"requests draft"| node_generation
node_api -->|"requests review"| node_review
node_generation -->|"generates content"| node_llm
node_review -->|"reviews draft"| node_llm
node_analyzer -.->|"writes report data"| node_render
node_cli -.->|"provides saved posts"| node_render

click node_api "https://github.com/sumitkr0843/trend_finder_backend/blob/main/api/main.py"
click node_cli "https://github.com/sumitkr0843/trend_finder_backend/blob/main/main.py"
click node_config "https://github.com/sumitkr0843/trend_finder_backend/blob/main/config/config.py"
click node_reddit "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/reddit.py"
click node_youtube "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/youtube.py"
click node_tiktok "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/tiktok.py"
click node_instagram "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/instagram.py"
click node_xsearch "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/x.py"
click node_ranking "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/ranking.py"
click node_analyzer "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py"
click node_generation "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py"
click node_review "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py"
click node_render "https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/render.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_api,node_cli,node_config,node_user toneBlue
class node_reddit,node_youtube,node_tiktok,node_instagram,node_xsearch toneAmber
class node_ranking,node_analyzer,node_apify toneMint
class node_generation,node_review,node_render toneRose
class node_firecrawl,node_llm toneIndigo
```

## Components

### Entry points

- [Search API](https://github.com/sumitkr0843/trend_finder_backend/blob/main/api/main.py): `api/main.py`
- [CLI workflow](https://github.com/sumitkr0843/trend_finder_backend/blob/main/main.py): `main.py`
- [Credentials config](https://github.com/sumitkr0843/trend_finder_backend/blob/main/config/config.py): `config/config.py`

### Social collection

- [Reddit search](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/reddit.py): `scripts/reddit.py`
- [YouTube search](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/youtube.py): `scripts/youtube.py`
- [TikTok search](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/tiktok.py): `scripts/tiktok.py`
- [Instagram search](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/instagram.py): `scripts/instagram.py`
- [X search](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/x.py): `scripts/x.py`

### Analysis and ranking

- [Engagement ranking](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/ranking.py): `scripts/ranking.py`
- [Trend mining](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py): `scripts/analyzer.py`

### Content and reporting

- [Draft generation](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py): `scripts/analyzer.py`
- [Draft review](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/analyzer.py): `scripts/analyzer.py`
- [HTML dashboard](https://github.com/sumitkr0843/trend_finder_backend/blob/main/scripts/render.py): `scripts/render.py`

### Other components

- **User**
- **Apify actors**
- **Firecrawl search**
- **OpenAI service**

## Connections

- User → Search API: submits requests (evidence: `api/main.py`)
- User → CLI workflow: enters niche (evidence: `main.py`)
- Search API → Reddit search: dispatches search (evidence: `api/main.py`)
- Search API → YouTube search: dispatches search (evidence: `api/main.py`)
- Search API → TikTok search: dispatches search (evidence: `api/main.py`)
- Search API → Instagram search: dispatches search (evidence: `api/main.py`)
- Search API → X search: dispatches search (evidence: `api/main.py`)
- CLI workflow → Reddit search: dispatches search (evidence: `main.py`)
- CLI workflow → YouTube search: dispatches search (evidence: `main.py`)
- CLI workflow → TikTok search: dispatches search (evidence: `main.py`)
- CLI workflow → Instagram search: dispatches search (evidence: `main.py`)
- Reddit search → Credentials config: reads key (evidence: `scripts/reddit.py`)
- YouTube search → Credentials config: reads token (evidence: `scripts/youtube.py`)
- TikTok search → Credentials config: reads token (evidence: `scripts/tiktok.py`)
- Instagram search → Credentials config: reads token (evidence: `scripts/instagram.py`)
- X search → Credentials config: reads token (evidence: `scripts/x.py`)
- Trend mining → Credentials config: reads model settings (evidence: `scripts/analyzer.py`)
- Reddit search → Firecrawl search: searches web (evidence: `scripts/reddit.py`)
- YouTube search → Apify actors: runs actor (evidence: `scripts/youtube.py`)
- TikTok search → Apify actors: runs actor (evidence: `scripts/tiktok.py`)
- Instagram search → Apify actors: runs actors (evidence: `scripts/instagram.py`)
- X search → Apify actors: runs actor (evidence: `scripts/x.py`)
- Search API → Engagement ranking: ranks results (evidence: `api/main.py`)
- Search API → Trend mining: mines trends (evidence: `api/main.py`)
- CLI workflow → Engagement ranking: ranks results (evidence: `main.py`)
- CLI workflow → Trend mining: mines trends (evidence: `main.py`)
- CLI workflow → HTML dashboard: renders dashboard (evidence: `main.py`)
- Trend mining → OpenAI service: requests completion (evidence: `scripts/analyzer.py`)
- Search API → Draft generation: requests draft (evidence: `api/main.py`)
- Search API → Draft review: requests review (evidence: `api/main.py`)
- Draft generation → OpenAI service: generates content (evidence: `scripts/analyzer.py`)
- Draft review → OpenAI service: reviews draft (evidence: `scripts/analyzer.py`)
- Trend mining → HTML dashboard: writes report data
- CLI workflow → HTML dashboard: provides saved posts (evidence: `main.py`)
