# eugeneyan/news-agents architecture

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

- Interactive diagram: https://gitdiagram.com/eugeneyan/news-agents
- Repository: https://github.com/eugeneyan/news-agents

## Overview

##### Project type and purpose
- This is an open-source, terminal-based news aggregation system.
- It leverages Amazon Q CLI as an agent orchestration harness, the Model Context Protocol (MCP) for parsing RSS feeds, and tmux to run multiple agents in parallel.
- Its goal is to fetch articles from various sources, summarize them with AI agents, and produce both individual feed summaries and one consolidated digest.

##### File structure
- Top level
– feeds.txt: list of feed URLs
– pyproject.toml, uv.lock: Python dependency and lockfiles
– context/: markdown files containing instructions/prompts for each agent role
– src/: Python modules
· main.py: entrypoint, spawns and supervises agents
· ainews.py, hackernews.py, techcrunch.py, wired.py, wsj.py: feed-specific fetch & parse logic
– summaries/: output directory for per-feed and main summaries
- Patterns
– Orchestration vs. worker code are separated: main.py vs feed modules
– Context files decouple prompt definitions from code

##### README for additional insights
- Architecture overview section describes:
- Main Agent reads feeds.txt, splits URLs into three chunks
- Three Sub-Agents run in parallel (in tmux panes) to process chunks
- Each Sub-Agent fetches, parses, summarizes, and writes to summaries/
- Main Agent collects all sub-summaries and produces main-summary.md
- Technology stack: Amazon Q CLI, MCP, tmux, Python with httpx and mcp[cli]

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Orchestration Layer
    QCLI["Amazon Q CLI (harness)"]:::cli
    QCLI -->|"starts"| MainAgent["Main Agent Process"]:::agent

    %% Context Files
    subgraph "Context Files" 
        MainCtx["main-agent.md"]:::context
        SubCtx["sub-agent.md"]:::context
        MainTemp["main-summary-template.md"]:::context
        SubTemp["sub-summary-template.md"]:::context
    end
    MainCtx --> MainAgent
    MainTemp --> MainAgent
    SubCtx --> SA1
    SubCtx --> SA2
    SubCtx --> SA3

    %% Parallel Execution via tmux
    MainAgent -->|"spawns tmux"| Tmux["tmux Server"]:::external
    subgraph "Sub-Agent Workers"
        direction TB
        SA1["Sub-Agent 1"]:::agent
        SA2["Sub-Agent 2"]:::agent
        SA3["Sub-Agent 3"]:::agent
    end
    Tmux --> SA1
    Tmux --> SA2
    Tmux --> SA3
    SA1 -->|"reports done"| MainAgent
    SA2 -->|"reports done"| MainAgent
    SA3 -->|"reports done"| MainAgent

    %% Feed Processors
    subgraph "Feed Processors"
        direction TB
        AINewsProc["ainews.py"]:::code
        HackerProc["hackernews.py"]:::code
        TCProc["techcrunch.py"]:::code
        WiredProc["wired.py"]:::code
        WSJProc["wsj.py"]:::code
    end
    SA1 -->|"uses"| AINewsProc
    SA1 -->|"uses"| HackerProc
    SA2 -->|"uses"| TCProc
    SA2 -->|"uses"| WiredProc
    SA3 -->|"uses"| WSJProc

    %% External RSS Feeds
    subgraph "External RSS Feeds"
        direction TB
        AINewsFeed["AI News"]:::external
        HNFeed["Hacker News"]:::external
        TCFeed["TechCrunch"]:::external
        WiredFeed["Wired"]:::external
        WSJFeed["WSJ"]:::external
    end
    AINewsProc -->|"GET RSS"| AINewsFeed
    HackerProc -->|"GET RSS"| HNFeed
    TCProc -->|"GET RSS"| TCFeed
    WiredProc -->|"GET RSS"| WiredFeed
    WSJProc -->|"GET RSS"| WSJFeed

    %% Storage
    subgraph "Storage"
        direction TB
        SummariesDir["summaries/"]:::storage
        MainSum["main-summary.md"]:::storage
    end
    AINewsProc -->|"writes summary"| SummariesDir
    HackerProc -->|"writes summary"| SummariesDir
    TCProc -->|"writes summary"| SummariesDir
    WiredProc -->|"writes summary"| SummariesDir
    WSJProc -->|"writes summary"| SummariesDir
    MainAgent -->|"aggregates to"| MainSum

    %% Initial Inputs
    FeedsList["feeds.txt"]:::storage
    QCLI -->|"reads"| FeedsList
    MainAgent -->|"splits chunks"| FeedsList

    %% Dependencies & Docs
    README["README.md"]:::storage
    UVLock["uv.lock"]:::storage

    %% Click Events
    click QCLI "https://github.com/eugeneyan/news-agents/blob/main/pyproject.toml"
    click MainAgent "https://github.com/eugeneyan/news-agents/blob/main/src/main.py"
    click MainCtx "https://github.com/eugeneyan/news-agents/blob/main/context/main-agent.md"
    click SubCtx "https://github.com/eugeneyan/news-agents/blob/main/context/sub-agent.md"
    click MainTemp "https://github.com/eugeneyan/news-agents/blob/main/context/main-summary-template.md"
    click SubTemp "https://github.com/eugeneyan/news-agents/blob/main/context/sub-summary-template.md"
    click FeedsList "https://github.com/eugeneyan/news-agents/blob/main/feeds.txt"
    click AINewsProc "https://github.com/eugeneyan/news-agents/blob/main/src/ainews.py"
    click HackerProc "https://github.com/eugeneyan/news-agents/blob/main/src/hackernews.py"
    click TCProc "https://github.com/eugeneyan/news-agents/blob/main/src/techcrunch.py"
    click WiredProc "https://github.com/eugeneyan/news-agents/blob/main/src/wired.py"
    click WSJProc "https://github.com/eugeneyan/news-agents/blob/main/src/wsj.py"
    click SummariesDir "https://github.com/eugeneyan/news-agents/tree/main/summaries/"
    click MainSum "https://github.com/eugeneyan/news-agents/blob/main/summaries/main-summary.md"

    %% Styles
    classDef agent fill:#c6f5c6,stroke:#2d882d
    classDef cli fill:#e0f5c6,stroke:#6d882d
    classDef external fill:#c6dfff,stroke:#2d4a88
    classDef storage fill:#fff8b3,stroke:#b38f2d
    classDef context fill:#ffd9b3,stroke:#b36a2d
    classDef code fill:#e0e0e0,stroke:#888888
```
