GitHub Repository Evaluator

A comprehensive web application for evaluating and prioritizing GitHub repositories for open-source contributions. Features automated scoring, detailed metrics analysis, and team collaboration tools.

🚀 Features

• Automated Analysis: Fetches repository data from GitHub API and calculates objective metrics
• Smart Scoring: Weighted algorithm evaluates 7 key metrics for comprehensive scoring
• Visual Dashboard: Interactive charts, tables, and progress indicators
• Team Collaboration: Share evaluations, track contribution status, and prioritize projects
• Custom UI: Professional, non-generic interface with smooth animations
• Responsive Design: Works seamlessly across desktop, tablet, and mobile devices

📊 Scoring Metrics

Metric	Weight	Description
Activity	20%	Commit frequency, issues, releases in last 90 days
Maintainer Response	20%	Average response time to issues and PRs
Guidelines	15%	Quality of contribution documentation
Code Structure	15%	Organization, modularity, ease of navigation
Test Coverage	10%	Testing infrastructure and CI/CD
Community	10%	Engagement, discussions, welcoming atmosphere
Relevance	10%	Alignment with your interests and tech stack

🛠 Tech Stack

• Frontend: Next.js 14, React 18, TypeScript
• Styling: Tailwind CSS with custom components
• State Management: Zustand
• Database: PostgreSQL with Prisma ORM
• API Integration: GitHub REST and GraphQL APIs
• Charts: Recharts
• Testing: Jest, React Testing Library, Playwright
• Deployment: Vercel (recommended)

📦 Installation

1. Clone or download the repository

   # If you have this code in a git repository:
   git clone <your-repository-url>
   cd github-repo-evaluator
   
   # Or simply navigate to your project directory if you have the files locally
   cd github-repo-evaluator

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env.local

   Fill in your environment variables:

   DATABASE_URL="postgresql://username:password@localhost:5432/github_repo_evaluator"
   GITHUB_TOKEN="your_github_personal_access_token"

4. Set up the database

   npx prisma generate
   npx prisma db push
   npx prisma db seed

5. Start the development server

   npm run dev

6. Open your browser Navigate to http://localhost:3000

🔧 Development Commands

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server

# Database
npx prisma studio    # Open database GUI
npx prisma migrate dev  # Run database migrations
npx prisma db seed   # Seed database with test data

# Testing
npm run test         # Run unit tests
npm run test:e2e     # Run end-to-end tests
npm run test:coverage # Generate coverage report

# Code quality
npm run lint         # ESLint
npm run type-check   # TypeScript checking

🚀 Deployment

Vercel (Recommended)

1. Connect your repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

Manual Deployment

1. Build the application

   npm run build

2. Set up production database

   • Create PostgreSQL database
   • Run migrations: npx prisma migrate deploy

3. Configure environment variables

   DATABASE_URL="your_production_database_url"
   GITHUB_TOKEN="your_github_token"
   NEXTAUTH_URL="https://your-domain.com"
   NEXTAUTH_SECRET="your_nextauth_secret"

📖 Usage

Adding Repositories

1. Paste GitHub URL: Enter any GitHub repository URL
2. Automatic Analysis: System fetches data and calculates metrics
3. Manual Scoring: Rate subjective metrics (guidelines, community, relevance)
4. View Results: Get comprehensive score and detailed breakdown

Dashboard Features

• Filter & Sort: Filter by score, language, status; sort by any metric
• View Modes: Switch between table and grid views
• Export Data: Download repository data as CSV
• Refresh Data: Update repository metrics from GitHub
• Status Tracking: Mark repositories as evaluated, watching, contributed, or completed

Action Buttons

• Open Issues: Direct link to "good first issue" filtered issues
• View README: Quick access to repository documentation
• Contact Maintainers: Link to discussions or issue creation

🧪 Testing

The project includes comprehensive testing:

• Unit Tests: Components, utilities, and services
• Integration Tests: API routes and database operations
• End-to-End Tests: Complete user workflows
• Coverage Target: 80% minimum coverage

Run tests:

npm run test           # Unit and integration tests
npm run test:e2e       # End-to-end tests
npm run test:coverage  # Coverage report

🤝 Contributing

1. Create a feature branch: git checkout -b feature/amazing-feature
2. Commit your changes: git commit -m 'Add amazing feature'
3. Push to the branch: git push origin feature/amazing-feature
4. Create a Pull Request (if using a git hosting service)

📄 License

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

🙏 Acknowledgments

• GitHub API for repository data
• Open source community for inspiration
• Contributors and testers

📞 Support

If you encounter any issues or have questions:

1. Check the application logs for error details
2. Ensure all environment variables are properly configured
3. Verify your GitHub token has the necessary permissions
4. Check the database connection and migrations

---

Happy Contributing! 🎉