🌟 GitHub Starred Repositories Dashboard

A dynamic, visually appealing dashboard for GitHub starred repositories that supports multiple usernames. Features Ruby backend data generation with JavaScript frontend, GitHub Pages compatibility, and automated data updates via GitHub Actions.

✨ Features

• 🎨 Beautiful UI: Modern, responsive dashboard with Bootstrap styling
• 👤 Multi-user Support: Enter any GitHub username to view their starred repos
• 🏷️ Language Grouping: Repositories organized by programming language with color-coded badges
• 📊 Rich Metadata: Shows stars, topics, reading time estimates, and last updated dates
• 🚀 GitHub Pages Ready: Deploy as a static site with optional dynamic data generation
• 🔄 Auto-Updates: GitHub Actions workflow for automated data refresh
• 🧪 Fully Tested: Comprehensive test suites for both Ruby and JavaScript code

🚀 Quick Start

Option 1: View the Live Demo

Simply open index.html in your browser to see the dashboard with sample data.

Option 2: Generate Your Own Data

1. Clone the repository

   git clone <your-repo-url>
   cd github-ruby-project

2. Install Ruby dependencies

   bundle install

3. Set up your GitHub token

   cp .env.example .env
   # Edit .env and add your GitHub token

4. Generate data for a user

   ruby fetch-starred.rb your-github-username

5. Serve the dashboard

   python3 -m http.server 8000
   # Open http://localhost:8000 in your browser

📁 Project Structure

github-ruby-project/
├── 📄 index.html              # Main dashboard page
├── 📄 script.js               # Dashboard JavaScript logic
├── 📄 github-api.js           # GitHub API integration
├── 📄 fetch-starred.rb        # Ruby data fetcher
├── 📄 Gemfile                 # Ruby dependencies
├── 📄 .env                    # Environment variables (create from .env.example)
├── 📄 config.example.js       # JavaScript config template
├── 🧪 simple_test.rb          # Ruby backend tests
├── 🧪 test_frontend.js        # JavaScript command-line tests
├── 🧪 test_frontend.html      # Interactive browser tests
├── 📁 output/                 # Generated JSON data files
│   ├── starred_grouped_<user>.json
│   └── starred_<user>.json
└── 📁 .github/workflows/      # GitHub Actions automation
    └── generate-user-data.yml

🛠️ Setup Instructions

Prerequisites

• Ruby 3.0+
• Node.js (for frontend tests)
• GitHub Personal Access Token

1. Environment Setup

Create .env file:

cp .env.example .env

Add your GitHub token to .env:

GITHUB_TOKEN=your_github_personal_access_token_here

Get a GitHub token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate new token with public_repo scope
3. Copy the token to your .env file

2. Install Dependencies

Ruby dependencies:

bundle install

For testing (optional):

# Node.js should be installed for frontend tests
node --version

3. Configuration

For local development with dynamic features:

// Copy config.example.js to config.js
cp config.example.js config.js

// Edit config.js:
window.GITHUB_CONFIG = {
  owner: 'your-github-username',
  repo: 'your-repository-name', 
  token: 'your_github_token' // Only for local development!
};

For GitHub Pages deployment:

// In config.js (or keep config.example.js):
window.GITHUB_CONFIG = {
  owner: 'your-github-username',
  repo: 'your-repository-name',
  token: null  // Always null for production!
};

📖 Usage

Generate Data for Any User

# Generate data for a specific user
ruby fetch-starred.rb octocat

# Generate data for yourself (default)
ruby fetch-starred.rb

This creates JSON files in the output/ directory:

• starred_grouped_<username>.json - Repositories grouped by language
• starred_<username>.json - Flat list of repositories

View the Dashboard

Local development:

# Serve files over HTTP (required for JavaScript to work)
python3 -m http.server 8000
# or
ruby -run -e httpd . -p 8000

# Open http://localhost:8000 in your browser

GitHub Pages:

1. Push your repository to GitHub
2. Enable GitHub Pages in repository settings
3. Your dashboard will be available at https://username.github.io/repository-name

Using the Dashboard

1. Enter a username in the form at the top
2. Click "Load Repositories" to fetch data
3. View organized repos grouped by programming language
4. Click repository names to visit them on GitHub

🧪 Testing

Ruby Backend Tests

# Run Ruby tests
ruby simple_test.rb

Tests cover:

• Reading time estimation
• Language color validation
• Data structure validation

JavaScript Frontend Tests

Command line tests:

# Run JavaScript tests with Node.js
node test_frontend.js

Interactive browser tests:

# Open in browser
open test_frontend.html
# Click "Run All Tests" button

Frontend tests cover:

• HTML generation functions
• Username validation
• Date formatting
• JSON data processing
• Error handling
• URL validation
• DOM manipulation

Test Results

✅ Ruby Tests: 34 passed, 0 failed
✅ JavaScript Tests: 69 passed, 0 failed

🔄 GitHub Actions Integration

Automated Data Generation

The repository includes a GitHub Actions workflow that can generate user data automatically:

Workflow file: .github/workflows/generate-user-data.yml

Manual trigger:

1. Go to Actions tab in your GitHub repository
2. Select "Generate User Data" workflow
3. Click "Run workflow"
4. Enter the username you want to generate data for

API trigger (from JavaScript): The dashboard can automatically trigger the workflow when data for a user doesn't exist.

Setup for GitHub Actions

1. Add GitHub token as repository secret:

   • Go to Settings → Secrets and variables → Actions
   • Add new secret: GITHUB_TOKEN with your personal access token

2. Enable workflow permissions:

   • Go to Settings → Actions → General
   • Set "Workflow permissions" to "Read and write permissions"

🎨 Customization

Adding New Languages

Edit the LANGUAGE_COLORS constant in fetch-starred.rb:

LANGUAGE_COLORS = {
  "Ruby" => "#701516",
  "YourLanguage" => "#your-hex-color",
  # ... other languages
}

Styling Changes

The dashboard uses Bootstrap 5.3.0. Customize by:

1. Editing CSS in index.html
2. Modifying the HTML generation in script.js
3. Updating the card templates

Data Fields

To add new data fields, update:

1. fetch-starred.rb - Add fields to the data structure
2. script.js - Update HTML generation to display new fields
3. Tests - Add validation for new fields

🚀 Deployment

GitHub Pages (Recommended)

1. Push to GitHub
2. Enable Pages: Settings → Pages → Source: Deploy from branch → main
3. Pre-generate data: Run ruby fetch-starred.rb username for expected users
4. Commit JSON files: Add generated files to repository
5. Access: https://username.github.io/repository-name

Other Static Hosts

The dashboard works on any static hosting service:

• Netlify
• Vercel
• GitHub Pages
• Firebase Hosting
• Any web server

🔒 Security Notes

• Never commit .env files - Contains your GitHub token
• Use token: null in production - Keep tokens out of client-side code
• Use repository secrets - For GitHub Actions workflows
• Limit token permissions - Only grant necessary scopes (public_repo)

🐛 Troubleshooting

"Failed to fetch" Error

Problem: JavaScript can't load JSON files
Solution: Serve files over HTTP, not file:// protocol

python3 -m http.server 8000

"No data found" Message

Problem: JSON files don't exist for the requested user
Solution: Generate data first

ruby fetch-starred.rb username

GitHub API Rate Limits

Problem: Too many API requests
Solution:

• Use authenticated requests (add GitHub token)
• Wait for rate limit reset
• Cache generated JSON files

Tests Timing Out

Problem: Tests hang or timeout
Solution:

• Check internet connection
• Verify GitHub token is valid
• Run simpler tests first: ruby simple_test.rb

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: ruby simple_test.rb && node test_frontend.js
5. Commit changes: git commit -am 'Add feature'
6. Push to branch: git push origin feature-name
7. Submit a Pull Request

License

This project is open source and available under the MIT License.

Acknowledgments

• GitHub API for providing repository data
• Bootstrap for UI components
• Ruby HTTParty for HTTP requests
• GitHub Actions for automation

---