Project Overview - sansan0/TrendRadar

Source Files

This page is generated from the following source files:

ProjectIntroduction

TrendRadar is a lightweight, highly deployable news aggregation and analysis tool designed to filter information overload. It enables users to deploy a personalized news monitoring service in approximately 30 seconds (README-EN.md:7). The project focuses on delivering only relevant news updates to users through various notification channels, supporting multi-platform data aggregation and AI-enhanced analysis.

The core value proposition lies in its "lightweight and easy to deploy" design philosophy (README-EN.md:45). It abstracts away the complexity of crawling, deduplication, translation, and push notifications, providing a unified configuration interface. The system supports a wide array of notification channels, including WeChat, Telegram, DingTalk, Feishu, Email, and generic Webhooks (README-EN.md:19-28), making it suitable for both individual developers and team monitoring needs.

TechnologyStack

The project is built with a modern Python stack, prioritizing asynchronous performance and compatibility with AI standards.

Technology	Version/Constraint	Purpose
Python	>=3.10	Core runtime environment (pyproject.toml:5)
FastMCP	2.12.0 - 2.14.0	Model Context Protocol server implementation for AI integration (pyproject.toml:10)
LiteLLM	1.57.0 - 2.0.0	Unified interface for LLM providers, enabling AI analysis features (pyproject.toml:14)
Requests	2.32.5 - 3.0.0	HTTP client for fetching news feeds and API calls (pyproject.toml:7)
Feedparser	6.0.0 - 7.0.0	RSS/Atom feed parsing engine (pyproject.toml:12)
PyYAML	6.0.3 - 7.0.0	Configuration file parsing (pyproject.toml:9)
Boto3	1.35.0 - 2.0.0	AWS SDK (likely for SNS/SES notifications or cloud storage) (pyproject.toml:13)
Tenacity	8.5.0	Retry logic for handling network failures robustly (pyproject.toml:15)

CoreFeatures

TrendRadar provides a comprehensive suite of features aimed at automating the information consumption workflow.

Unified Scheduling System (v6.0.0)

The v6.0.0 update introduced a major overhaul of the scheduling mechanism via timeline.yaml. This system decouples crawling, pushing, and analysis schedules, allowing for fine-grained control over when the system is active (README-EN.md:198).

Preset Templates: Includes 5 built-in modes such as always_on (24/7), office_hours (work hours only), and night_owl (README-EN.md:199).
Flexible Periods: Supports different configurations for weekdays vs. weekends and cross-midnight time periods (README-EN.md:200).

Multi-Source Aggregation

The system aggregates data from multiple platforms. It relies on the newsnow project API for multi-platform data fetching (README-EN.md:85), abstracting the complexity of dealing with various news site structures.

AI-Enhanced Analysis

TrendRadar integrates AI capabilities to process raw news.

MCP Support: It acts as an MCP (Model Context Protocol) server, allowing AI clients to connect and analyze the news data (README-EN.md:34).
Translation: Supports AI-powered multi-language translation for non-native content (README-EN.md:17).

Diverse Notification Channels

The project supports a wide range of push notification services to ensure users receive updates on their preferred platforms.

Supported Platforms: WeWork, WeChat, Telegram, DingTalk, Feishu, Email, ntfy, Bark, Slack, and generic Webhooks (README-EN.md:19-28).
Generic Webhook: Allows for custom integration with any system that accepts HTTP POST requests (README-EN.md:28).

SystemArchitecture

The system is designed around a modular architecture where data ingestion, processing, and notification are loosely coupled. The following diagram illustrates the high-level component interaction and data flow.

正在加载图表渲染器...

Architecture Explanation:

Ingestion: The system relies on external APIs (like newsnow) and standard RSS feeds. The Requests client handles network calls, while Feedparser standardizes the content format.
Core Processing: The Timeline Scheduler (v6.0.0 feature) acts as the conductor, triggering tasks based on timeline.yaml (README-EN.md:198). Data flows through deduplication and filtering logic before reaching the user.
AI Layer: The MCP Server exposes tools to external AI clients. The LiteLLM module allows the system to call various LLMs for content analysis or translation (pyproject.toml:14).
Delivery: The Notification Router abstracts the specifics of different push services, dispatching messages to the configured channels.

KeyDataFlow

The following sequence diagram details the lifecycle of a news item from fetching to final delivery, highlighting the interaction between the scheduler, core logic, and notification modules.

正在加载图表渲染器...

Data Flow Explanation:

Scheduling: The process begins with the Timeline Scheduler initiating a crawl event. This is controlled by the new timeline.yaml configuration, which replaces the older push_window logic (README-EN.md:196).
Fetching: The Fetcher utilizes requests and feedparser to retrieve and parse raw data from external sources.
Processing: The Core Engine validates the data. It removes duplicates and filters items based on user-defined keywords.
AI Integration: If AI analysis is enabled, the core engine sends the content to the AI Agent. This agent uses LiteLLM to interface with various LLM providers for tasks like summarization or translation (pyproject.toml:14).
Notification: Finally, the Notifier takes the processed (and optionally AI-analyzed) content and formats it for the specific target channel (e.g., Markdown for Telegram, HTML for Email) before pushing it to the user.

ProjectStructure

The project structure is organized to separate configuration, source code, and server logic.

text
1trendradar/
2├── pyproject.toml          # Project metadata and dependencies
3├── README.md               # Chinese documentation
4├── README-EN.md            # English documentation
5├── trendradar/             # Main application package
6│   ├── __main__.py         # Entry point for CLI (`trendradar` command)
7│   ├── config.yaml         # Main configuration file (v2.0.0)
8│   ├── timeline.yaml       # Scheduling configuration (v6.0.0)
9│   └── frequency_words.txt # Keyword filtering list
10└── mcp_server/             # MCP Server implementation
11    └── server.py           # Entry point for MCP (`trendradar-mcp`)

Structure Notes:

The entry points are defined in pyproject.toml: trendradar for the main CLI and trendradar-mcp for the MCP server (pyproject.toml:18-20).
Configuration is split into config.yaml (settings) and timeline.yaml (scheduling), reflecting the v6.0.0 architecture update (README-EN.md:198).

DeploymentScenarios

TrendRadar is designed for flexibility in deployment, catering to different user environments.

1. GitHub Actions (Zero Cost)

The project supports "one-click fork" deployment via GitHub Actions (README-EN.md:31). This is ideal for users who want a free, serverless solution. The workflow runs periodically to fetch news and send notifications.

2. Docker (Self-Hosted)

For users requiring privacy or higher frequency control, Docker deployment is supported (README-EN.md:33). An official image is available on Docker Hub (wantcat/trendradar). This method allows the user to control the cron schedule and resource usage.

3. MCP Client Integration

Developers can run the trendradar-mcp server to integrate TrendRadar's capabilities into AI applications (like Claude Desktop or IDEs) (README-EN.md:34). This allows the AI to query current trends or news summaries dynamically.