# themessimagic/ytnews architecture

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

- Interactive diagram: https://gitdiagram.com/themessimagic/ytnews
- Repository: https://github.com/themessimagic/ytnews

## Overview

AI News Portal monitors a YouTube channel, extracts a new video's transcript, generates and parses a structured article, then stores it for the Flask site to publish. The site also tracks page visits in PostgreSQL and exposes protected analytics. The workflow and integrations are documented or visible in the sampled app.py and watcher.py; templates and deployment automation are represented only where the README documents their role.

Main entry points: [`watcher.py`](https://github.com/themessimagic/ytnews/blob/main/watcher.py) (Channel watcher), [`app.py`](https://github.com/themessimagic/ytnews/blob/main/app.py) (Flask web app), [`templates/analytics.html`](https://github.com/themessimagic/ytnews/blob/main/templates/analytics.html) (Analytics dashboard), [`articles`](https://github.com/themessimagic/ytnews/tree/main/articles) (Article JSON files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content_pipeline["Article generation"]
  node_watcher["Channel watcher<br/>[watcher.py]"]
  node_youtube_api["YouTube Data API"]
  node_transcript_service["Apify transcript scraper"]
  node_transcript["Video transcript"]
  node_gemini["Gemini article writer"]
  node_article_parser["Article parser<br/>[watcher.py]"]
  node_watch_state[("Last-video state<br/>[state.json]")]
end

subgraph group_publishing["Article publishing"]
  node_article_store[("Article JSON files")]
  node_flask_site["Flask web app<br/>[app.py]"]
  node_article_pages["Article templates<br/>[article.html]"]
  node_home_page["News index<br/>[index.html]"]
end

subgraph group_analytics["Traffic analytics"]
  node_visitor_tracking["Visit tracking<br/>[app.py]"]
  node_analytics_db[("Analytics database")]
  node_analytics_api["Analytics API<br/>[app.py]"]
end

subgraph group_admin["Administration"]
  node_admin_templates["Admin pages<br/>[admin_login.html]"]
  node_analytics_template["Analytics dashboard<br/>[analytics.html]"]
  node_admin_auth["Admin authentication<br/>[app.py]"]
end

node_youtube_channel(("YouTube channel"))
node_reader(("Site visitor"))

node_youtube_channel -.->|"uploads videos"| node_youtube_api
node_watcher -->|"checks uploads"| node_youtube_api
node_youtube_api -->|"returns video details"| node_watcher
node_watcher -->|"requests transcript"| node_transcript_service
node_transcript_service -->|"returns segments"| node_watcher
node_watcher -->|"joins segments"| node_transcript
node_watcher -->|"generates article"| node_gemini
node_gemini -->|"returns article text"| node_watcher
node_watcher -->|"parses response"| node_article_parser
node_watcher -->|"fetches metadata"| node_youtube_api
node_watcher -->|"writes JSON"| node_article_store
node_watcher -->|"reads and updates"| node_watch_state
node_reader -.->|"requests pages"| node_flask_site
node_flask_site -->|"loads articles"| node_article_store
node_flask_site -.->|"renders index"| node_home_page
node_flask_site -.->|"renders article"| node_article_pages
node_flask_site -.->|"renders login"| node_admin_templates
node_flask_site -->|"checks admin access"| node_admin_auth
node_admin_auth -->|"serves dashboard"| node_analytics_template
node_flask_site -->|"tracks page views"| node_visitor_tracking
node_visitor_tracking -->|"writes visits"| node_analytics_db
node_flask_site -->|"serves reports"| node_analytics_api
node_analytics_api -->|"queries metrics"| node_analytics_db
node_analytics_template -.->|"requests metrics"| node_analytics_api

click node_watcher "https://github.com/themessimagic/ytnews/blob/main/watcher.py"
click node_article_parser "https://github.com/themessimagic/ytnews/blob/main/watcher.py"
click node_article_store "https://github.com/themessimagic/ytnews/tree/main/articles"
click node_watch_state "https://github.com/themessimagic/ytnews/blob/main/state.json"
click node_flask_site "https://github.com/themessimagic/ytnews/blob/main/app.py"
click node_article_pages "https://github.com/themessimagic/ytnews/blob/main/templates/article.html"
click node_home_page "https://github.com/themessimagic/ytnews/blob/main/templates/index.html"
click node_admin_templates "https://github.com/themessimagic/ytnews/blob/main/templates/admin_login.html"
click node_analytics_template "https://github.com/themessimagic/ytnews/blob/main/templates/analytics.html"
click node_visitor_tracking "https://github.com/themessimagic/ytnews/blob/main/app.py"
click node_analytics_api "https://github.com/themessimagic/ytnews/blob/main/app.py"
click node_admin_auth "https://github.com/themessimagic/ytnews/blob/main/app.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_watcher,node_youtube_api,node_transcript_service,node_transcript,node_gemini,node_article_parser,node_watch_state toneBlue
class node_article_store,node_flask_site,node_article_pages,node_home_page toneAmber
class node_visitor_tracking,node_analytics_db,node_analytics_api toneMint
class node_admin_templates,node_analytics_template,node_admin_auth toneRose
class node_youtube_channel,node_reader toneIndigo
```

## Components

### Article generation

- [Channel watcher](https://github.com/themessimagic/ytnews/blob/main/watcher.py): `watcher.py`
- **YouTube Data API**
- **Apify transcript scraper**
- **Video transcript**
- **Gemini article writer**
- [Article parser](https://github.com/themessimagic/ytnews/blob/main/watcher.py): `watcher.py`
- [Last-video state](https://github.com/themessimagic/ytnews/blob/main/state.json): `state.json`

### Article publishing

- [Article JSON files](https://github.com/themessimagic/ytnews/tree/main/articles): `articles`
- [Flask web app](https://github.com/themessimagic/ytnews/blob/main/app.py): `app.py`
- [Article templates](https://github.com/themessimagic/ytnews/blob/main/templates/article.html): `templates/article.html`
- [News index](https://github.com/themessimagic/ytnews/blob/main/templates/index.html): `templates/index.html`

### Traffic analytics

- [Visit tracking](https://github.com/themessimagic/ytnews/blob/main/app.py): `app.py`
- **Analytics database**
- [Analytics API](https://github.com/themessimagic/ytnews/blob/main/app.py): `app.py`

### Administration

- [Admin pages](https://github.com/themessimagic/ytnews/blob/main/templates/admin_login.html): `templates/admin_login.html`
- [Analytics dashboard](https://github.com/themessimagic/ytnews/blob/main/templates/analytics.html): `templates/analytics.html`
- [Admin authentication](https://github.com/themessimagic/ytnews/blob/main/app.py): `app.py`

### Other components

- **YouTube channel**
- **Site visitor**

## Connections

- YouTube channel → YouTube Data API: uploads videos (evidence: `README.md`)
- Channel watcher → YouTube Data API: checks uploads (evidence: `watcher.py`)
- YouTube Data API → Channel watcher: returns video details (evidence: `watcher.py`)
- Channel watcher → Apify transcript scraper: requests transcript (evidence: `watcher.py`)
- Apify transcript scraper → Channel watcher: returns segments (evidence: `watcher.py`)
- Channel watcher → Video transcript: joins segments (evidence: `watcher.py`)
- Channel watcher → Gemini article writer: generates article (evidence: `watcher.py`)
- Gemini article writer → Channel watcher: returns article text (evidence: `watcher.py`)
- Channel watcher → Article parser: parses response (evidence: `watcher.py`)
- Channel watcher → YouTube Data API: fetches metadata (evidence: `watcher.py`)
- Channel watcher → Article JSON files: writes JSON (evidence: `watcher.py`)
- Channel watcher → Last-video state: reads and updates (evidence: `watcher.py`)
- Site visitor → Flask web app: requests pages (evidence: `README.md`)
- Flask web app → Article JSON files: loads articles (evidence: `app.py`)
- Flask web app → News index: renders index (evidence: `README.md`)
- Flask web app → Article templates: renders article (evidence: `README.md`)
- Flask web app → Admin pages: renders login (evidence: `README.md`)
- Flask web app → Admin authentication: checks admin access (evidence: `app.py`)
- Admin authentication → Analytics dashboard: serves dashboard (evidence: `app.py`)
- Flask web app → Visit tracking: tracks page views (evidence: `app.py`)
- Visit tracking → Analytics database: writes visits (evidence: `app.py`)
- Flask web app → Analytics API: serves reports (evidence: `app.py`)
- Analytics API → Analytics database: queries metrics (evidence: `app.py`)
- Analytics dashboard → Analytics API: requests metrics (evidence: `app.py`)