📸Video

Git.Grade.mp4

Note to Judges: The application processes real-time data from GitHub. Please allow a few seconds for the AI analysis to complete after clicking "Analyze".

---

GitGrade 🚀

Theme: AI + Code Analysis + Developer Profiling Event: Unsaid Talks™ GitGrade Hackathon Tagline: Unfold Success from Untold Experiences

GitGrade is an intelligent "Repository Mirror" that evaluates GitHub repositories to provide students and developers with an honest score, a mentor-style summary, and a personalized roadmap for improvement.

---

🎯 Problem Statement

In the modern tech landscape, a GitHub repository is a developer's tangible portfolio. However, most students and early-career developers do not know how their code looks to a recruiter or mentor. They often lack:

• Actionable feedback on code cleanliness and consistency.
• Understanding of "production-ready" standards vs. "academic" code.
• A clear path to improve their existing projects.

The Challenge: Design a system that accepts a repository URL, automatically fetches data, and generates a meaningful Score + Summary + Roadmap.

---

💡 Our Approach & Solution

GitGrade acts as an automated AI Coding Mentor. Instead of just checking for syntax errors, it evaluates the quality and maturity of the project.

1. Data Aggregation

The system uses the GitHub API to fetch public repository data, including:

• Metadata: Stars, forks, language distribution.
• File Structure: Analysis of folder hierarchy and organization.
• Content: The README.md, package.json (or equivalent), and samples of source code.
• History: Recent commit messages to analyze development consistency.

2. Multi-Dimensional AI Analysis

We utilize OpenAI (GPT-5) to analyze the aggregated data against 6 key dimensions:

• 🛠️ Code Quality: Readability, naming conventions, and patterns.
• 📂 Project Structure: Separation of concerns and file organization.
• 📄 Documentation: Clarity of the README and inline comments.
• 🧪 Test Coverage: Presence and quality of automated tests.
• 🌳 Git Practices: Commit message quality and frequency.
• 🌍 Real-World Relevance: Practical value and completeness.

3. The "Mentor" Persona

The AI is prompted to be honest but constructive, avoiding fake praise. It generates a 0-100 Score and assigns a Developer Level (Beginner, Intermediate, Advanced, Production-Ready).

---

✨ Key Features

• 📊 Smart Scoring Engine: Visualizes project health with a dynamic score ring.
• 🗺️ Personalized Roadmap: Generates specific tasks categorized by priority:
  • 🔴 Fix Now: Critical issues (e.g., missing .gitignore, sensitive data).
  • 🟡 Improve Soon: Best practices (e.g., adding CI/CD).
  • 🟢 Learn Next: Advanced architecture patterns.
• 📉 Detailed Metrics: Breakdown of scores across all 6 analyzed dimensions.
• ⚡ Modern Dashboard: A clean, responsive UI built with React, Tailwind CSS, and Shadcn UI.

---

🛠️ Tech Stack

Frontend

• Framework: React (Vite)
• Styling: Tailwind CSS + Shadcn UI
• State/Query: TanStack Query
• Visualization: Recharts

Backend

• Server: Node.js + Express
• AI Engine: OpenAI API
• Database: PostgreSQL
• ORM: Drizzle ORM

---

🚀 Installation & Setup

Follow these steps to run GitGrade locally.

Prerequisites

• Node.js (v18+)
• PostgreSQL database
• OpenAI API Key

Steps

1. Clone the Repository

   git clone [https://github.com/your-username/git-grade.git](https://github.com/your-username/git-grade.git)
   cd git-grade

2. Install Dependencies

   npm install

3. Environment Configuration Create a .env file in the root directory:

   DATABASE_URL=postgresql://user:password@localhost:5432/gitgrade
   OPENAI_API_KEY=sk-your-key-here
   PORT=5000

4. Setup Database Push the schema to your local database:

   npm run db:push

5. Run the Application Start the development server (runs both frontend and backend):

   npm run dev

   Open http://localhost:5000 in your browser.

---