# pandich93/youtube-niche-finder architecture

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

- Interactive diagram: https://gitdiagram.com/pandich93/youtube-niche-finder
- Repository: https://github.com/pandich93/youtube-niche-finder

## Overview

niche-finder is a YouTube research and planning product for creators, delivered through a web dashboard, Chrome extension, and MCP tools. Its core workflow collects and periodically snapshots YouTube data into a local corpus; discovery and scoring turn that history into niche and video insights; creator tools use those insights to evaluate ideas, prepare metadata, and schedule drafts. Separate branches cover competitor alerts and channel tracking, plus read-only analytics for connected creator channels. Relationships are based on README statements and the supplied source-index references; unsampled wiring is left unverified.

Main entry points: [`backend/interfaces/http/api.py`](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/interfaces/http/api.py) (HTTP API), [`backend/infrastructure/postgres/repositories.py`](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/postgres/repositories.py) (History database), [`backend/application/collecting.py`](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/collecting.py) (Corpus collection), [`backend/interfaces/mcp/server.py`](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/interfaces/mcp/server.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User interfaces"]
  node_dashboard["Web dashboard<br/>[router.js]"]
  node_extension["Chrome extension<br/>[content.js]"]
  node_mcp["MCP tools<br/>[server.py]"]
end

subgraph group_research["Research corpus"]
  node_collector["Corpus collection<br/>[collecting.py]"]
  node_discovery["Niche discovery<br/>[discovery.py]"]
  node_score["Niche scoring<br/>[score_catalog.py]"]
end

subgraph group_creator["Creator workflow"]
  node_briefs["Video briefs<br/>[briefs.py]"]
  node_metadata["Metadata review<br/>[metadata_review.py]"]
  node_calendar["Content calendar"]
end

subgraph group_operations["Tracking and operations"]
  node_scheduler["Scheduled worker<br/>[worker_cycle.py]"]
  node_alerts["Alerts<br/>[alerts.py]"]
  node_channeltrack["Channel tracking"]
  node_notify["Alert delivery<br/>[factory.py]"]
  node_own["Own-channel analytics<br/>[own_channels.py]"]
end

subgraph group_platform["Shared platform"]
  node_http["HTTP API<br/>[api.py]"]
  node_youtube["YouTube Data API<br/>[client.py]"]
  node_history[("History database<br/>[repositories.py]")]
  node_oauth["YouTube OAuth<br/>[oauth.py]"]
  node_analytics["YouTube Analytics API<br/>[analytics.py]"]
  node_plans["Plans and quotas<br/>[plans.py]"]
  node_llm["LLM gateway<br/>[llm_gateway.py]"]
end

node_creator(("Creator"))

node_creator -->|"uses"| node_dashboard
node_creator -->|"uses"| node_extension
node_creator -->|"queries"| node_mcp
node_dashboard -.->|"requests"| node_http
node_extension -.->|"requests"| node_http
node_http -->|"dispatches"| node_collector
node_http -->|"dispatches"| node_discovery
node_http -->|"dispatches"| node_alerts
node_http -->|"dispatches"| node_channeltrack
node_http -->|"dispatches"| node_briefs
node_http -->|"dispatches"| node_metadata
node_http -->|"dispatches"| node_calendar
node_mcp -->|"dispatches"| node_collector
node_mcp -->|"dispatches"| node_discovery
node_mcp -->|"dispatches"| node_channeltrack
node_scheduler -->|"runs"| node_collector
node_scheduler -->|"runs"| node_alerts
node_scheduler -->|"runs"| node_own
node_collector -->|"fetches"| node_youtube
node_collector -->|"stores"| node_history
node_discovery -->|"reads"| node_history
node_discovery -->|"scores"| node_score
node_alerts -->|"reads and writes"| node_history
node_alerts -->|"delivers"| node_notify
node_channeltrack -.->|"reads"| node_history
node_metadata -->|"reads"| node_history
node_calendar -->|"schedules drafts"| node_metadata
node_own -->|"authenticates"| node_oauth
node_own -->|"fetches metrics"| node_analytics
node_own -.->|"stores"| node_history
node_http -.->|"dispatches"| node_plans
node_metadata -.->|"uses"| node_llm

click node_dashboard "https://github.com/pandich93/youtube-niche-finder/blob/main/frontend/router.js"
click node_extension "https://github.com/pandich93/youtube-niche-finder/blob/main/extension/content.js"
click node_mcp "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/interfaces/mcp/server.py"
click node_http "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/interfaces/http/api.py"
click node_collector "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/collecting.py"
click node_scheduler "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/worker_cycle.py"
click node_youtube "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/youtube/client.py"
click node_history "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/postgres/repositories.py"
click node_discovery "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/discovery.py"
click node_score "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/domain/score_catalog.py"
click node_alerts "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/alerts.py"
click node_channeltrack "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/channel_tracking.py"
click node_notify "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/notify/factory.py"
click node_briefs "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/briefs.py"
click node_metadata "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/metadata_review.py"
click node_calendar "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/content_calendar.py"
click node_own "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/own_channels.py"
click node_oauth "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/youtube/oauth.py"
click node_analytics "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/youtube/analytics.py"
click node_plans "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/plans.py"
click node_llm "https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/llm_gateway.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_dashboard,node_extension,node_mcp toneBlue
class node_collector,node_discovery,node_score toneAmber
class node_briefs,node_metadata,node_calendar toneMint
class node_scheduler,node_alerts,node_channeltrack,node_notify,node_own toneRose
class node_http,node_youtube,node_history,node_oauth,node_analytics,node_plans,node_llm,node_creator toneIndigo
```

## Components

### User interfaces

- [Web dashboard](https://github.com/pandich93/youtube-niche-finder/blob/main/frontend/router.js): `frontend/router.js`
- [Chrome extension](https://github.com/pandich93/youtube-niche-finder/blob/main/extension/content.js): `extension/content.js`
- [MCP tools](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/interfaces/mcp/server.py): `backend/interfaces/mcp/server.py`

### Research corpus

- [Corpus collection](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/collecting.py): `backend/application/collecting.py`
- [Niche discovery](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/discovery.py): `backend/application/discovery.py`
- [Niche scoring](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/domain/score_catalog.py): `backend/domain/score_catalog.py`

### Creator workflow

- [Video briefs](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/briefs.py): `backend/application/briefs.py`
- [Metadata review](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/metadata_review.py): `backend/application/metadata_review.py`
- [Content calendar](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/content_calendar.py): `backend/application/content_calendar.py`

### Tracking and operations

- [Scheduled worker](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/worker_cycle.py): `backend/application/worker_cycle.py`
- [Alerts](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/alerts.py): `backend/application/alerts.py`
- [Channel tracking](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/channel_tracking.py): `backend/application/channel_tracking.py`
- [Alert delivery](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/notify/factory.py): `backend/infrastructure/notify/factory.py`
- [Own-channel analytics](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/own_channels.py): `backend/application/own_channels.py`

### Shared platform

- [HTTP API](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/interfaces/http/api.py): `backend/interfaces/http/api.py`
- [YouTube Data API](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/youtube/client.py): `backend/infrastructure/youtube/client.py`
- [History database](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/postgres/repositories.py): `backend/infrastructure/postgres/repositories.py`
- [YouTube OAuth](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/youtube/oauth.py): `backend/infrastructure/youtube/oauth.py`
- [YouTube Analytics API](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/infrastructure/youtube/analytics.py): `backend/infrastructure/youtube/analytics.py`
- [Plans and quotas](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/plans.py): `backend/application/plans.py`
- [LLM gateway](https://github.com/pandich93/youtube-niche-finder/blob/main/backend/application/llm_gateway.py): `backend/application/llm_gateway.py`

### Other components

- **Creator**

## Connections

- Creator → Web dashboard: uses (evidence: `README.md`)
- Creator → Chrome extension: uses (evidence: `README.md`)
- Creator → MCP tools: queries (evidence: `README.md`)
- Web dashboard → HTTP API: requests
- Chrome extension → HTTP API: requests
- HTTP API → Corpus collection: dispatches (evidence: `backend/interfaces/http/api.py`)
- HTTP API → Niche discovery: dispatches (evidence: `backend/interfaces/http/api.py`)
- HTTP API → Alerts: dispatches (evidence: `backend/interfaces/http/api.py`)
- HTTP API → Channel tracking: dispatches (evidence: `backend/interfaces/http/api.py`)
- HTTP API → Video briefs: dispatches (evidence: `backend/interfaces/http/api.py`)
- HTTP API → Metadata review: dispatches (evidence: `backend/interfaces/http/api.py`)
- HTTP API → Content calendar: dispatches (evidence: `backend/interfaces/http/api.py`)
- MCP tools → Corpus collection: dispatches (evidence: `backend/interfaces/mcp/server.py`)
- MCP tools → Niche discovery: dispatches (evidence: `backend/interfaces/mcp/server.py`)
- MCP tools → Channel tracking: dispatches (evidence: `backend/interfaces/mcp/server.py`)
- Scheduled worker → Corpus collection: runs (evidence: `backend/application/worker_cycle.py`)
- Scheduled worker → Alerts: runs (evidence: `backend/application/worker_cycle.py`)
- Scheduled worker → Own-channel analytics: runs (evidence: `backend/application/worker_cycle.py`)
- Corpus collection → YouTube Data API: fetches (evidence: `backend/application/collecting.py`)
- Corpus collection → History database: stores (evidence: `backend/application/collecting.py`)
- Niche discovery → History database: reads (evidence: `backend/application/discovery.py`)
- Niche discovery → Niche scoring: scores (evidence: `backend/domain/score_catalog.py`)
- Alerts → History database: reads and writes (evidence: `backend/application/alerts.py`)
- Alerts → Alert delivery: delivers (evidence: `README.md`)
- Channel tracking → History database: reads
- Metadata review → History database: reads (evidence: `backend/application/metadata_review.py`)
- Content calendar → Metadata review: schedules drafts (evidence: `backend/application/content_calendar.py`)
- Own-channel analytics → YouTube OAuth: authenticates (evidence: `backend/application/own_channels.py`)
- Own-channel analytics → YouTube Analytics API: fetches metrics (evidence: `backend/application/own_channels.py`)
- Own-channel analytics → History database: stores
- HTTP API → Plans and quotas: dispatches (evidence: `backend/interfaces/http/api.py`)
- Metadata review → LLM gateway: uses