# jacob5585/rss-summarizer architecture

> Architecture diagram of the GitHub repository jacob5585/rss-summarizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jacob5585/rss-summarizer
- Repository: https://github.com/jacob5585/rss-summarizer

## Overview

##### Project Type and Purpose
– This is a Python-based full-stack web application (likely using Flask) whose job is to:
- Periodically fetch news articles from various RSS feeds (finance, science, tech, world news).
- Summarize each article using an LLM (via Ollama).
- Optionally convert the summary to audio via a text-to-speech engine.
- Store raw articles, summaries, and audio files in local directories.
- Serve a simple web UI for users to browse summaries and playback audio, plus view logs.

##### File Structure
Top‐level directories/files:
– src/
- app.py – the Flask (or equivalent) web server, routes, and template rendering.
- main.py – entry point that likely orchestrates scheduled scraping and summarization runs.
- scrape_articles.py – contains RSS-feed-fetching and HTML-parsing logic.
- ollama_sum.py – wraps calls to the Ollama LLM for summarization.
- text2speech.py – handles conversion of text summaries to audio files.
- files.py – manages filesystem I/O (articles/, audio/, logs/).
- logs.py – configures and writes log entries under logs/.
- rss.py – RSS parser or feed-list definitions.
- requirements.txt – Python dependencies (Flask, feedparser, requests, Ollama SDK, TTS libraries, etc.).
– templates/
- main_menu.html – landing page with navigation.
- articles.html – displays article summaries and audio playback links.
- logs.html – displays application logs.
– articles/, audio/, logs/ – persistent storage for data and logs, organized by category.

##### README
– README is minimal but confirms “python rss feed summarizer application.”
– No explicit mention of database: the app uses flat files.
– No other external services besides RSS feeds and Ollama/​TTS libraries.

A. Presentation Layer (Frontend)
- Component: Flask Web Server (app.py)
- Templates: main_menu.html, articles.html, logs.html

B. Business Logic Layer (Backend Services)
1. RSS Scraper Service (scrape_articles.py + rss.py)
– Polls external RSS feed URLs → fetches & normalizes new articles.
2. Summarization Service (ollama_sum.py)
– Takes plain text → calls local/remote Ollama LLM → returns summary.
3. Text-to-Speech Service (text2speech.py)
– Takes summary text → converts to audio files (e.g., MP3/WAV).
4. File Management Service (files.py)
– Writes/reads summaries to articles/; audio files to audio/; log entries via logs/.
5. Logging Service (logs.py)
– Centralized logger → writes structured logs under logs/.

C. Storage Layer
- Local File System
– articles/finance|science|tech|world_news
– audio/finance|science|tech|world_news
– logs/

D. External Systems
- RSS Feed Providers (finance, science, tech, world news sites)
- Ollama LLM (local Docker container or remote API)
- Optional TTS API (if using a cloud service)

##### Relationships and Data Flows
1. User (Web Browser) → HTTP Request → Flask Web Server
a. “Fetch Latest Summaries” → triggers backend scrape → summarization → TTS → updates storage.
b. “View Articles” → Flask reads articles/ files → renders articles.html.
c. “Play Audio” → browser streams file from audio/ directory.
d. “View Logs” → Flask reads logs/ → renders logs.html.
2. Scraper Service → HTTP Requests → External RSS Feeds → Article HTML/Text
3. Summarization Service → gRPC/HTTP → Ollama → Summary Text
4. TTS Service → API call or library → Audio File
5. File Management Service → Disk I/O → articles/, audio/, logs/

##### Architectural Patterns and Design Principles
– Layered Architecture (Presentation / Business Logic / Storage).
– Separation of Concerns: each module handles a single responsibility.
– Batch vs. On-Demand: scraping/summarization can be scheduled (main.py) or invoked via UI.
– File-based persistence (no RDBMS) for simplicity.

– Annotations for any scheduling/rate-limiting (if present).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Presentation Layer
  subgraph "Presentation Layer"
    direction TB
    Browser["User Browser"]:::external
    Flask["Flask Web Server"]:::presentation
    TemplateMain["main_menu.html"]:::presentation
    TemplateArticles["articles.html"]:::presentation
    TemplateLogs["logs.html"]:::presentation
  end

  %% Business Logic Layer
  subgraph "Business Logic Layer"
    direction TB
    Orchestrator["Scheduler/Orchestrator (main.py)"]:::business
    Scraper["RSS Scraper Service"]:::business
    Parser["RSS Parser (rss.py)"]:::business
    Summarizer["Summarization Service"]:::business
    TTS["Text-to-Speech Service"]:::business
    FileMgr["File Management Service"]:::business
    Logger["Logging Service"]:::business
  end

  %% Storage Layer
  subgraph "Storage Layer"
    direction TB
    Articles["Article Files (articles/)"]:::storage
    Audio["Audio Files (audio/)"]:::storage
    LogsStorage["Logs (logs/)"]:::storage
  end

  %% External Systems
  subgraph "External Systems"
    direction TB
    RSSFeeds["RSS Feed Providers"]:::external
    Ollama["Ollama LLM"]:::external
    TTSAPI["Optional TTS API"]:::external
  end

  %% Connections
  Browser -->|HTTP Request| Flask
  Flask -->|Render Templates| TemplateMain
  Flask -->|Render Templates| TemplateArticles
  Flask -->|Render Templates| TemplateLogs
  Flask -->|Invoke Fetch| Orchestrator
  Flask -->|Read Articles| Articles
  Flask -->|Read Audio Files| Audio
  Flask -->|Read Logs| LogsStorage

  Orchestrator -.->|schedule| Scraper
  Scraper -->|uses| Parser
  Scraper -->|RSS XML Feed| RSSFeeds
  Scraper -->|Raw Article Text| FileMgr

  Scraper -->|new articles| FileMgr
  FileMgr -->|store articles| Articles

  FileMgr -->|log events| Logger
  Logger -->|write logs| LogsStorage

  FileMgr -->|text input| Summarizer
  Summarizer -->|calls LLM| Ollama
  Summarizer -->|Summary JSON| FileMgr
  FileMgr -->|store summaries| Articles

  FileMgr -->|text input| TTS
  TTS -->|calls API| TTSAPI
  TTS -->|Audio File| FileMgr
  FileMgr -->|store audio| Audio

  %% Click Events
  click Flask "https://github.com/jacob5585/rss-summarizer/blob/main/src/app.py"
  click TemplateMain "https://github.com/jacob5585/rss-summarizer/blob/main/templates/main_menu.html"
  click TemplateArticles "https://github.com/jacob5585/rss-summarizer/blob/main/templates/articles.html"
  click TemplateLogs "https://github.com/jacob5585/rss-summarizer/blob/main/templates/logs.html"
  click Orchestrator "https://github.com/jacob5585/rss-summarizer/blob/main/src/main.py"
  click Scraper "https://github.com/jacob5585/rss-summarizer/blob/main/src/scrape_articles.py"
  click Parser "https://github.com/jacob5585/rss-summarizer/blob/main/src/rss.py"
  click Summarizer "https://github.com/jacob5585/rss-summarizer/blob/main/src/ollama_sum.py"
  click TTS "https://github.com/jacob5585/rss-summarizer/blob/main/src/text2speech.py"
  click FileMgr "https://github.com/jacob5585/rss-summarizer/blob/main/src/files.py"
  click Logger "https://github.com/jacob5585/rss-summarizer/blob/main/src/logs.py"
  click Articles "https://github.com/jacob5585/rss-summarizer/tree/main/articles/finance"
  click Articles "https://github.com/jacob5585/rss-summarizer/tree/main/articles/science"
  click Articles "https://github.com/jacob5585/rss-summarizer/tree/main/articles/tech"
  click Articles "https://github.com/jacob5585/rss-summarizer/tree/main/articles/world_news"
  click Audio "https://github.com/jacob5585/rss-summarizer/tree/main/audio/finance"
  click Audio "https://github.com/jacob5585/rss-summarizer/tree/main/audio/science"
  click Audio "https://github.com/jacob5585/rss-summarizer/tree/main/audio/tech"
  click Audio "https://github.com/jacob5585/rss-summarizer/tree/main/audio/world_news"
  click LogsStorage "https://github.com/jacob5585/rss-summarizer/tree/main/logs/"

  %% Styles
  classDef presentation fill:#cce5ff,stroke:#004085,color:#004085
  classDef business fill:#d4edda,stroke:#155724,color:#155724
  classDef storage fill:#ffeeba,stroke:#856404,color:#856404
  classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
