Skip to content

README.md

Latest commit

 

History

History
286 lines (209 loc) · 9.18 KB

README.md

File metadata and controls

286 lines (209 loc) · 9.18 KB
Raw

🌟 GitHub Stars Constellation

A beautiful and interactive web application that visualizes your GitHub starred repositories as a network graph. Discover connections between your favorite projects based on shared languages, organizations, dependencies, and topics.

GitHub Stars Constellation Python React FastAPI

📸 Screenshots

Dashboard View

Dashboard View Overview of your starred repositories with statistics and detailed repository cards

Graph View with Filters

Graph View with Filters Interactive network graph with comprehensive filtering options

Interactive Network Graph

Network Graph Force-directed visualization showing repository connections

Network Graph with Repository Cards

Network Graph with Repository Cards Network visualization with detailed repository cards below showing metadata

✨ Features

  • Interactive Network Graph: Force-directed visualization of repository connections
  • Rich Repository Metadata: Stars, forks, languages, topics, and descriptions
  • Multiple Connection Types: Same language, organization, shared dependencies, and topics
  • Advanced Filtering: Filter by stars, forks, languages, organizations, and more
  • Search & Discovery: Find specific repositories quickly
  • Real-time Sync: Keep your data up to date with GitHub
  • Beautiful UI: Modern, responsive design with GitHub-inspired theming
  • Zoom & Navigation: Explore your repository network with smooth interactions

🚀 Quick Start

Prerequisites

  • Python 3.8+ and Node.js 16+
  • GitHub Personal Access Token (see setup instructions below)
  • UV package manager (recommended) or pip

1. Clone the Repository

git clone https://github.com/yourusername/git-stars.git
cd git-stars

2. Set Up Your GitHub Token

  1. Generate a Personal Access Token:

    • Go to GitHub Settings > Developer settings > Personal access tokens
    • Click "Generate new token (classic)"
    • Give it a name like "GitHub Stars Constellation"
    • Select these scopes:
      • ✅ public_repo (to read public repositories)
      • ✅ read:user (to read your user information)
    • Click "Generate token"
    • Copy the token immediately (you won't see it again!)

  2. Create Environment File:

    cp .env.example .env

  3. Add Your Token:

    # Edit .env file and add your token
GITHUB_TOKEN=your_github_token_here
PORT=8001

3. Install Dependencies

# Install Python dependencies
make install

# Or manually with uv
uv sync

4. Run the Application

# Start both backend and frontend
make run

# Or run them separately
make backend    # Backend only (http://localhost:8001)
make frontend   # Frontend only (http://localhost:5173)

5. Access the Application

📖 How to Use

Initial Setup

  1. First Visit: When you first open the application, you'll see an empty dashboard
  2. Sync Your Stars: Click the "Sync Stars" button in the header to import your GitHub starred repositories
  3. Wait for Processing: The sync process will fetch your repositories and build the network graph

Dashboard View

The Dashboard provides an overview of your starred repositories:

  • Statistics Cards: Total repositories, top languages, top organizations, star distribution
  • Repository List: Detailed cards showing each repository with metadata
  • Timeline: Repository creation timeline by year

Graph View

The Graph shows an interactive network visualization:

  • Nodes: Each circle represents a repository (size indicates popularity)
  • Edges: Lines show connections between repositories
  • Colors: Nodes are color-coded by programming language

Graph Interactions

  • Hover over nodes: See repository details in tooltips
  • Click nodes: View detailed repository information
  • Hover over edges: See connection type (Same Language, Same Organization, etc.)
  • Drag nodes: Reposition repositories in the graph
  • Zoom controls: Use the buttons in the top-right to zoom in/out
  • Search: Use the search bar to find specific repositories
  • Toggle labels: Show/hide repository names on the graph

Graph Filters

Click "Filters" to customize your view:

  • Basic Filters: Minimum stars, max repositories, minimum forks
  • Connection Types: Choose which relationships to show
  • Advanced Filters: Filter by languages, organizations, sort options

Tips for Best Experience

  1. Start with Dashboard: Get familiar with your data first
  2. Use Filters: Reduce clutter by filtering to specific languages or organizations
  3. Explore Connections: Hover over edges to understand relationships
  4. Zoom In: Use zoom to explore dense areas of the graph
  5. Search: Quickly find specific repositories you're interested in

🛠️ Development

Project Structure

git-stars/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # API endpoints
│   │   ├── core/           # Configuration
│   │   ├── database/       # Database models
│   │   ├── services/       # Business logic
│   │   └── main.py         # FastAPI app
├── frontend-react/         # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── lib/           # Utilities and API
│   │   └── types/         # TypeScript types
├── .env                    # Environment variables
├── Makefile               # Development commands
└── pyproject.toml         # Python dependencies

Available Commands

# Development
make run              # Start both servers
make backend          # Start backend only
make frontend         # Start frontend only
make install          # Install dependencies

# Code Quality
make lint             # Run linting
make format           # Format code
make test             # Run tests

# Cleanup
make clean            # Remove build artifacts
make clean-venv       # Remove virtual environment

API Endpoints

  • GET /health - Health check
  • GET /api/v1/repositories/ - List repositories
  • GET /api/v1/repositories/stats - Repository statistics
  • POST /api/v1/repositories/sync - Sync repositories
  • GET /api/v1/data - Graph data with filters

🔧 Configuration

Environment Variables

Create a .env file in the project root:

GITHUB_TOKEN=your_github_personal_access_token
PORT=8001
DEBUG=false

GitHub Token Scopes

Your GitHub token needs these permissions:

  • public_repo - Read public repositories
  • read:user - Read user information

🐛 Troubleshooting

Common Issues

  1. "Failed to sync repositories"

    • Check your GitHub token is valid and has correct permissions
    • Ensure the token is properly set in .env file

  2. "Address already in use"

    • Kill existing processes: pkill -f "uvicorn\|vite"
    • Or change the port in .env file

  3. "No repositories found"

    • Click "Sync Stars" to import your data
    • Check your GitHub account has starred repositories

  4. Graph not loading

    • Ensure backend is running on port 8001
    • Check browser console for errors
    • Try refreshing the page

Getting Help

  • Check the API documentation for backend details
  • Review browser console for frontend errors
  • Ensure all dependencies are installed: make install

📊 What the Graph Shows

The network graph visualizes connections between your starred repositories:

  • Same Language: Repositories written in the same programming language
  • Same Organization: Repositories from the same GitHub organization
  • Shared Dependencies: Repositories that use similar libraries/frameworks
  • Shared Topics: Repositories with overlapping GitHub topics

This helps you discover:

  • Which languages you prefer
  • Which organizations you follow
  • Related projects you might be interested in
  • Patterns in your repository interests

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Happy exploring your GitHub constellation! 🌟