GitHub Trends Weekly

GitHub 热门项目周报系统 / GitHub Trending Weekly Report Generator

A full-stack web application that automatically collects and displays trending GitHub repositories weekly. Built with FastAPI, React, and SQLite.

English | 中文

---

English

Features

• Automatic Collection: Scheduled weekly GitHub trending repositories collection
• Dashboard: Interactive web UI with charts and statistics
• Project Details: Detailed view with README preview and star history
• Search & Filter: Search projects by name, language, or topic
• Watch List: Track specific projects of interest
• Trend Prediction: AI-powered star growth prediction
• Export: Download reports in Markdown format
• REST API: Programmatic access to all data
• Docker Support: One-click deployment with Docker Compose

Tech Stack

Layer	Technology
Frontend	React 18 + TypeScript
UI Library	Ant Design 5
Charts	ECharts 5
Backend	FastAPI (Python 3.11)
Database	SQLite
Deployment	Docker + Nginx

Quick Start (Local Development)

Prerequisites

• Python 3.9+
• Node.js 18+
• GitHub Personal Access Token

1. Clone the Repository

git clone https://github.com/suriyel/github-trends-weekly.git
cd github-trends-weekly

2. Backend Setup

cd backend

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env and add your GitHub Token
# GITHUB_TOKEN=your_github_token_here

3. Run Backend

cd backend
uvicorn app.main:app --reload

The API will be available at http://localhost:8000

4. Frontend Setup (new terminal)

cd frontend
npm install
npm run dev

The app will be available at http://localhost:5173

5. Access the Application

Open http://localhost:5173 in your browser. Click "Refresh" to trigger data collection.

---

Docker Deployment

Prerequisites

• Docker 24+
• Docker Compose

Quick Start

# Clone and navigate to project
git clone https://github.com/suriyel/github-trends-weekly.git
cd github-trends-weekly

# Create .env file
cp .env.example .env
# Edit .env with your GitHub Token

# Start containers
docker-compose up -d

# Access the application
# Frontend: http://localhost
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs

Stopping

docker-compose down

---

Configuration

Environment Variables

Variable	Required	Description
GITHUB_TOKEN	Yes	GitHub Personal Access Token
WEBHOOK_URL	No	Notification webhook URL
API_ACCESS_TOKEN	No	API protection token

config.yaml

See Configuration Reference for full configuration options.

---

API Documentation

Once the backend is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

Method	Endpoint	Description
GET	/api/reports	List all reports
GET	/api/projects	List projects with filters
POST	/api/collect	Trigger data collection
GET	/api/stats/languages	Language statistics
GET	/api/stats/trends	Weekly trends

---

Development

# Run tests
cd backend
pytest

# Run with coverage
pytest --cov=app --cov-branch --cov-report=term-missing

# Run mutation tests
mutmut run

---

License

MIT License

---

中文

功能特性

• 自动采集: 定时收集 GitHub 热门项目
• 仪表盘: 交互式 Web UI，含图表和统计
• 项目详情: 完整信息展示，含 README 预览和 star 历史
• 搜索筛选: 按名称、语言、主题搜索项目
• 关注列表: 跟踪感兴趣的项目
• 趋势预测: AI 驱动的 star 增长预测
• 导出功能: 支持 Markdown 格式导出
• REST API: 提供完整的编程接口
• Docker 支持: 一键 Docker 部署

技术栈

层级	技术
前端	React 18 + TypeScript
UI 库	Ant Design 5
图表	ECharts 5
后端	FastAPI (Python 3.11)
数据库	SQLite
部署	Docker + Nginx

本地开发快速开始

前置要求

• Python 3.9+
• Node.js 18+
• GitHub Personal Access Token

1. 克隆项目

git clone https://github.com/suriyel/github-trends-weekly.git
cd github-trends-weekly

2. 后端设置

cd backend

# 创建虚拟环境
python -m venv .venv

# 激活 (Linux/macOS)
source .venv/bin/activate

# 激活 (Windows)
.venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 复制环境变量模板
copy .env.example .env

# 编辑 .env，添加 GitHub Token
# GITHUB_TOKEN=your_github_token_here

3. 启动后端

cd backend
uvicorn app.main:app --reload

API 地址: http://localhost:8000

4. 前端设置 (新终端)

cd frontend
npm install
npm run dev

应用地址: http://localhost:5173

5. 访问应用

在浏览器中打开 http://5173，点击"刷新"按钮触发数据采集。

---

Docker 部署

前置要求

• Docker 24+
• Docker Compose

快速开始

# 克隆并进入项目目录
git clone https://github.com/suriyel/github-trends-weekly.git
cd github-trends-weekly

# 创建 .env 文件
cp .env.example .env
# 编辑 .env，添加 GitHub Token

# 启动容器
docker-compose up -d

# 访问应用
# 前端: http://localhost
# 后端 API: http://localhost:8000
# API 文档: http://localhost:8000/docs

停止

docker-compose down

---

配置说明

环境变量

变量	必填	说明
GITHUB_TOKEN	是	GitHub Personal Access Token
WEBHOOK_URL	否	通知 Webhook URL
API_ACCESS_TOKEN	否	API 保护令牌

config.yaml

详见 配置参考。

---

API 文档

后端启动后访问:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

主要接口

方法	端点	说明
GET	/api/reports	获取报告列表
GET	/api/projects	获取项目列表（支持筛选）
POST	/api/collect	触发数据采集
GET	/api/stats/languages	语言统计
GET	/api/stats/trends	周趋势

---

开发

# 运行测试
cd backend
pytest

# 运行覆盖率
pytest --cov=app --cov-branch --cov-report=term-missing

# 变异测试
mutmut run

---

许可证

MIT License