# joyce677/trendradar architecture

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

- Interactive diagram: https://gitdiagram.com/joyce677/trendradar
- Repository: https://github.com/joyce677/trendradar

## Overview

##### Project type and purpose
- TrendRadar is an open-source “hot-trend” aggregator and notifier tool.
- It periodically pulls trending topics from multiple platforms (via the newsnow API), filters them by user-defined keywords, generates multi-format outputs (HTML, JSON, TXT), and pushes notifications to chat/notification services.

##### File structure
- .github/workflows/crawler.yml → GitHub Actions schedule
- main.py → core crawler + filter + output + notification logic
- config/config.yaml & config/frequency_words.txt → behavior and keyword configuration
- output/YYYYMMDD/... → timestamped archives of HTML and TXT snapshots
- api/trends.json → machine-readable JSON feed
- index.html & img/ → static-site entrypoint, assets
- docker/ → Dockerfile, docker-compose.yml, entrypoint.sh, manage.py for containerized deployment

##### README for additional insights
- Three report modes: daily/current/incremental
- Multi-channel webhook support: Enterprise WeChat, Feishu, DingTalk, Telegram
- GitHub Pages hosting of static output
- Docker & GitHub Actions for zero-tech, 30-second deployments

a. Main components:
– Scheduler: GitHub Actions (crawler.yml) or Docker cron (entrypoint.sh)
– TrendRadar Service: Python main.py + config files
– External Data Sources: newsnow API endpoints for each platform
– Storage: Git repo “output/” folder (HTML/TXT), api/trends.json
– Notification Endpoints: Webhook receivers (WeChat, Feishu, DingTalk, Telegram)
– Hosting: GitHub Pages serving static index.html + output
b. Relationships & interactions:
- Scheduler → invokes TrendRadar Service
- Service → HTTP GET → newsnow API (multiple source IDs)
- Service → processes & filters → writes to output folder & api/trends.json
- Service → HTTP POST → each configured webhook URL
- GitHub repo → GitHub Pages → end users view static site
c. Architectural patterns/design principles:
- ETL pipeline (Extract from newsnow, Transform via keyword rules, Load into static files)
- Configuration-driven (all behavior in YAML & TXT)
- Infrastructure-as-code (GitHub Actions + Docker Compose)
d. Key technologies/frameworks/libraries:
- Python 3.x (main.py)
- newsnow API
- YAML/TXT for config
- GitHub Actions (workflow)
- Docker (container & compose)
- Webhook integrations (HTTP POST)
- GitHub Pages (static hosting)

##### Be detailed but not cluttered
– Highlight extensibility: annotate config files as “extension points.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scheduler Layer
    subgraph "Scheduler Layer"
        GH["GitHub Actions\n.crawler.yml"]:::infra
        DC["Docker Cron\nentrypoint.sh"]:::infra
    end

    %% Service Layer
    subgraph "Service Layer"
        SR["TrendRadar Service\nmain.py"]:::processing
        CFG["Configuration\nconfig/config.yaml"]:::processing
        KEY["Keywords\nconfig/frequency_words.txt"]:::processing
    end

    %% External Data Sources
    API["newsnow API"]:::external

    %% Storage Layer
    subgraph "Storage Layer"
        OUT["Static Output\noutput/"]:::storage
        JSON["Local API Feed\napi/trends.json"]:::storage
    end

    %% Notification Endpoints
    WEB["Notification Endpoints\nWeChat, Feishu, DingTalk, Telegram"]:::external

    %% Hosting Layer
    subgraph "Hosting Layer"
        GI["GitHub Pages\nindex.html + img/"]:::infra
        CNAME["Custom Domain\nCNAME"]:::infra
    end

    %% Development Files
    README["Project README\nREADME.md"]:::infra
    REQ["Requirements\nrequirements.txt"]:::infra
    DCMP["Docker Compose\ndocker-compose.yml"]:::infra
    DFILE["Dockerfile\nDockerfile"]:::infra
    MNG["Container Management\nmanage.py"]:::infra

    %% Connections
    GH -->|"runs script"| SR
    DC -->|"runs script"| SR
    SR -->|"uses config"| CFG
    SR -->|"uses keywords"| KEY
    SR -->|"HTTP GET"| API
    SR -->|"writes HTML/TXT"| OUT
    SR -->|"updates JSON"| JSON
    SR -->|"HTTP POST"| WEB
    OUT -->|"served by"| GI
    GI -->|"uses domain"| CNAME

    %% Click Events
    click GH "https://github.com/joyce677/trendradar/blob/main/.github/workflows/crawler.yml"
    click DC "https://github.com/joyce677/trendradar/blob/main/docker/entrypoint.sh"
    click DCMP "https://github.com/joyce677/trendradar/blob/main/docker/docker-compose.yml"
    click DFILE "https://github.com/joyce677/trendradar/tree/main/docker/Dockerfile"
    click SR "https://github.com/joyce677/trendradar/blob/main/main.py"
    click CFG "https://github.com/joyce677/trendradar/blob/main/config/config.yaml"
    click KEY "https://github.com/joyce677/trendradar/blob/main/config/frequency_words.txt"
    click JSON "https://github.com/joyce677/trendradar/blob/main/api/trends.json"
    click OUT "https://github.com/joyce677/trendradar/tree/main/output/"
    click GI "https://github.com/joyce677/trendradar/blob/main/index.html"
    click GI "https://github.com/joyce677/trendradar/tree/main/img/"
    click MNG "https://github.com/joyce677/trendradar/blob/main/docker/manage.py"
    click README "https://github.com/joyce677/trendradar/blob/main/README.md"
    click REQ "https://github.com/joyce677/trendradar/blob/main/requirements.txt"
    click CNAME "https://github.com/joyce677/trendradar/tree/main/CNAME"

    %% Styles
    classDef infra fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef processing fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef storage fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef external fill:#e1bee7,stroke:#8e24aa,color:#4a148c
```
