GitGraph

Modern SaaS platform for analyzing repository health, tracking development metrics, and generating actionable insights for engineering teams. GitGraph is written in Typescript, React/Next.js and PostgreSQL

---

---

⚓ Overview

GitGraph is a high-end analytics platform for GitHub repositories designed to help developers and teams understand the health of their projects.

The platform evaluates multiple aspects of a repository, including:

• Technical debt indicators
• Codebase health metrics
• Development activity
• Repository structure insights
• Language distribution
• AI-driven analysis

All results are aggregated into a Health Score that reflects the overall condition of a repository.

The platform also provides exportable reports, allowing teams to share insights and track improvements over time.

---

⚓ Tech Stack

GitGraph was built using a modern full-stack architecture focused on performance, scalability, and a polished user experience.

Frontend

Backend

Data & Analytics

Export & Reports

---

1️⃣ Connect GitHub Account

Users begin by connecting their GitHub profile securely using OAuth authentication.

Start by connecting your GitHub profile.
GitGraph uses this connection to access your repositories and provide a personalized analysis of your development workflow.

---

2️⃣ Select Repositories

Choose which repositories should be monitored.

Select specific repositories to generate a complete overview of your projects.

---

3️⃣ AI Repository Analysis

GitGraph scans the selected repository and calculates the Health Score.

The analysis evaluates:

• Technical debt signals
• Security risks
• Community adoption
• Structural issues

All results contribute to the repository health score.

---

4️⃣ Review Insights

Detailed reports help developers understand what needs attention.

Insights are categorized by severity so developers can quickly prioritize improvements.

---

5️⃣ Reports & Export

Repositories can be analyzed through comprehensive reports and exported for external use.

Available exports:

• PDF Reports
• CSV Metrics
• JSON Data

These exports allow teams to:

• track technical debt reduction
• share analytics with stakeholders
• archive repository health snapshots

---

📦 Installation

Clone the repository:

git clone https://github.com/Gustaavo-404/gitgraph.git
cd gitgraph

Install dependencies:

npm install

---

⚙️ Environment Variables

Create a .env file in the root directory.

Example configuration:

DATABASE_URL="postgresql://user:password@localhost:5432/gitgraph"

GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

NEXTAUTH_SECRET=""
NEXTAUTH_URL="http://localhost:3000"

---

🗄 Database Setup (Prisma)

Generate Prisma client:

npx prisma generate

Run migrations:

npx prisma migrate dev

This will:

• create the database schema
• generate the Prisma client
• sync models with PostgreSQL

You can also open Prisma Studio:

npx prisma studio

---

▶️ Running the Development Server

Start the development server:

npm run dev

Then open:

http://localhost:3000

The application will automatically reload when changes are made.

---

📊 Key Features

• GitHub Repository Connection – Secure OAuth integration to connect personal repositories or entire organizations.

• Repository Metrics Dashboard – View essential project metrics such as stars, forks, open issues, contributors, and repository activity.

• AI-Powered Health Score – Composite score based on activity, development processes, maintainability, PR load, and repository popularity.

• Development Activity Insights – Analyze commit frequency and development trends over the last 7, 30, and 90 days.

• Language Distribution – Visualize the composition of the codebase with detailed language usage charts.

• Developer Insights – Understand contributor activity, team participation, and approximate development lead time.

• Exportable Reports – Generate downloadable analytics reports in PDF, CSV, and JSON formats.

---

🧱 Architecture

GitGraph follows a modular architecture.

Next.js (App Router)
│
├── Authentication (GitHub OAuth)
├── Repository Analytics Engine
├── Metrics Processing
├── Visualization Layer (D3)
├── Export Engine (Puppeteer)
└── Database Layer (Prisma + PostgreSQL)

---

🎯 Use Cases

GitGraph is designed for:

• engineering teams
• tech leads
• open-source maintainers
• SaaS teams
• individual developers tracking project health

---

📈 Future Roadmap

Planned improvements:

• complete documentation site
• full responsive interface (mobile & tablet support)
• improved dashboard and analytics experience
• landing page enhancements
• historical repository analytics
• CI/CD integrations
• automated health alerts

---

📄 License

GitGraph is licensed under the MIT License.

---

⚓ GitGraph — Understand, measure, and improve the health of your codebase.