TideScope

<div align="center"> <img src="web/public/logo-option-1.svg" alt="TideScope Logo" width="560"/> <p><strong>Make Technical Debt Visible, Make Open Source Collaboration Easier</strong></p> <p> <a href="README_CN.md">中文文档</a> &nbsp;|&nbsp; <a href="#quick-start">Quick Start</a> &nbsp;|&nbsp; <a href="#tech-stack">Tech Stack</a> &nbsp;|&nbsp; <a href="#contributing">Contributing</a> </p> </div>

---

💫 Our Mission

As a beginner, have you ever found an open source project that interests you, but struggled to figure out what you could contribute? Where to start?

As an open source project maintainer, have you ever felt overwhelmed by the flood of PRs and Issues, unsure how to prioritize tasks and manage technical debt?

TideScope is inspired by star maps. By scanning GitHub repositories for Issues, PRs, and TODO comments in code, combined with LLM-powered intelligent analysis to extract required skills and difficulty assessments, it generates an intuitive Technical Debt StarMap. Each task appears as a star, distributed in a polar coordinate system by importance from center to edge, with related PR-Issue pairs forming constellation-like visual clusters.

Through this innovative visualization approach, we aim to help:

• 🌱 New contributors quickly find tasks matching their skill level
• 🎯 Project maintainers gain a clear overview of technical debt at a glance
• 🤝 Team collaboration become more efficient, transparent, and organized

---

✨ Core Features

🌌 StarMap Visualization

• Ranking-Based Golden Angle Spiral Layout - Mathematically optimized distribution algorithm ensures uniform node placement
• Force-Directed Anti-Overlap Mechanism - Intelligent repulsion algorithm prevents node collisions, keeping the chart clear
• Constellation-Style Clustering - PRs and Issues automatically form tight constellation groups, intuitively showing relationships
• Gradient Glow Effects - Modern visual design optimized for dark themes

🧠 Intelligent Analysis

• LLM Skill Extraction - Automatically analyzes required tech stacks and skill points for each task
• Multi-Dimensional Scoring - Comprehensive assessment of priority, difficulty, impact scope, and risk level
• Smart Recommendations - Generates targeted implementation suggestions for each task
• Automatic Context - Automatically fetches project README as analysis background

🎯 Developer Friendly

• One-Click Scanning - Supports both local code and remote GitHub repositories
• Flexible Configuration - YAML config files for easy customization of scan rules
• Dual Interface - Web UI + CLI command line to meet different use cases

---

🖼️ Demo

StarMap View

Example using SurfSense project <img width="1332" height="1164" alt="QQ_1763474452961" src="https://github.com/user-attachments/assets/1e99fb0f-2c35-41d6-b1c9-c9d70fbfc4f2" /> <img width="2416" height="807" alt="image" src="https://github.com/user-attachments/assets/a66a87f0-c8bc-42b5-b798-d84be218369d" />

StarMap Features:

• 🎯 Important tasks in the center circle, priority decreases outward
• 🌟 Golden lines connect related PRs and Issues, forming "constellations"
• 🔍 Hover for details: title, skills, difficulty, recommendations
• 🎨 Glow effects and animations enhance visual experience
• 🌀 Golden angle spiral distribution, nodes evenly fill the entire space

Task Detail Assessment

Intelligent analysis example

Assessment Content:

• 📊 Priority: Auto-calculated (based on labels, update time, relevance)
• 🎓 Required Skills: LLM auto-extraction (e.g., Docker, Authentication, Database, Backend)
• 📈 Difficulty: Smart assessment (1-5 scale)
• 💡 Recommendations: Specific implementation steps and considerations
• 🔗 Related: Auto-identify related PRs and discussions

---

🎨 Dual System Architecture

TideScope provides two core systems to meet different needs:

1️⃣ Badge System - Best Entry Point for New Contributors

Core Value: Lower the barrier to open source contribution, help beginners quickly find suitable tasks

🎯 System Features

• 📊 Project Health Dashboard

  • Real-time health score (0-100)
  • Project activity trend analysis
  • Open Issues and PR statistics

• 🎖️ AI-Powered Task Badges

  • Auto-generate beautiful SVG badges
  • Display task title, difficulty, required skills
  • One-click jump to GitHub Issue

• 🌱 Beginner-Friendly Task List

  • Filter Issues suitable for beginners
  • Categorized by difficulty and skills
  • Includes detailed implementation suggestions

• 📝 Auto-Generate CONTRIBUTING.md

  • AI analyzes project to generate contribution guide
  • Includes health metrics, recommended tasks, skill distribution
  • Beautiful Markdown format, GitHub-ready

🔧 Technical Implementation

Workflow:

GitHub API → Data Fetch → LLM/Rule Analysis → SVG Generation → Markdown Rendering

Core Components:

1. analyzer/smart_analyzer.py - Smart Analyzer

   • Automatically choose LLM or rule-based analysis
   • Extract required skills from Issues
   • Assess task difficulty and priority

2. utils/hero_badge_generator.py - Hero Badge Generator

   • Generate project health panel
   • Create recommended task badges
   • Support multiple themes and sizes

3. scripts/generate_contributing.py - Documentation Generator

   • Auto-generate CONTRIBUTING.md
   • Integrate health, tasks, and skill information
   • Support custom templates

Output Files:

badges/
├── CONTRIBUTING.md          # AI-generated contribution guide
├── README.md                # Project README snippet
├── PREVIEW.html             # Local preview page
└── assets/
    ├── hero_badge.svg       # Project hero badge
    ├── health_panel.svg     # Health panel
    ├── recommended_task.svg # Recommended task badge
    └── beginner_task_*.svg  # Beginner task badges

💡 Use Cases

• ✅ Open Source Maintainers: One-click professional contribution guide
• ✅ New Contributors: Quickly understand project health and recommended tasks
• ✅ Team Collaboration: Unified task priority and skill requirements

---

2️⃣ Star Map System - Universe View of Technical Debt

Core Value: Visualize technical debt as a starry sky, making management intuitive and engaging

🌌 System Features

• Polar Coordinate Layout

  • Based on Golden Angle Spiral (137.5°)
  • Important tasks in center, priority decreases outward
  • Node size reflects impact scope

• Constellation-Style Clustering

  • PRs and Issues connected by golden lines forming "constellations"
  • Auto-identify relationships between related tasks
  • Visualize project module division

• Interactive Exploration

  • Hover to view task details (title, skills, difficulty, recommendations)
  • Click to jump to GitHub
  • Support zoom and pan

• Multi-Dimensional Analysis

  • Color-coded by difficulty (green-orange-red)
  • Categorized by status (Open/Closed/Merged)
  • Skill tag visualization

🔧 Technical Implementation

Workflow:

GitHub API → Scan Issues/PRs → LLM Analysis → Coordinate Calculation → ECharts Rendering

Core Components:

1. scanner/github/client.py - GitHub Data Fetcher

   • Batch fetch Issues and PRs
   • Handle pagination and rate limits
   • Caching mechanism to reduce API calls

2. analyzer/builder.py - Analysis Engine

   • Multi-dimensional scoring (priority, difficulty, impact)
   • LLM skill extraction and recommendation generation
   • Relationship identification

3. analyzer/star_map.py - StarMap Coordinate Algorithm

   • Golden angle spiral layout
   • Square root radius mapping
   • Force-directed anti-overlap optimization

4. web/src/pages/StarMapPage.tsx - Frontend Visualization

   • ECharts polar coordinate chart
   • Interactive nodes and connections
   • Responsive design

Output Files:

reports/
├── tidescope-raw.json       # Raw scan data
└── tidescope-report.json    # Analysis report (with coordinates)

💡 Use Cases

• ✅ Project Maintainers: Global view of technical debt management
• ✅ Team Leads: Identify critical paths and bottlenecks
• ✅ Product Managers: Understand dev resource allocation
• ✅ Developers: Find interesting modules and tasks

---

🛠️ Tech Stack

🐍 Backend Technologies

| Technology | Version | Purpose | |------------|---------|----------| | Python | 3.8+ | Core programming language | | Pydantic | 2.x | Data validation and modeling | | HTTPX | Latest | Async HTTP client (GitHub API) | | PyYAML | Latest | Configuration file parsing | | python-dotenv | Latest | Environment variable management | | FastAPI | Latest | REST API framework (Optional, for Web UI) | | Typer | Latest | Advanced CLI tool (Optional) |

🎨 Frontend Technologies (Web UI)

| Technology | Version | Purpose | |------------|---------|----------| | React | 18 | Modern UI framework | | TypeScript | Latest | Type-safe development | | Apache ECharts | 5.x | Data visualization (polar charts) | | Ant Design | 5.x | UI component library | | Vite | 5.x | Fast build tool |

🤖 LLM Integration

| Provider | Model | Notes | |----------|-------|-------| | Deepseek | deepseek-chat | Recommended: Cost-effective, relaxed rate limits | | OpenAI | gpt-4o-mini | Alternative: Powerful, higher cost |

LLM Analysis Content:

• Extract required skills (e.g., React, TypeScript, Docker)
• Assess difficulty (1-5 scale)
• Generate implementation recommendations

Fallback Strategy:

• Automatically uses rule-based ana