GitHub Insight Engine

January 24, 2026 · View on GitHub

The most powerful GitHub analytics API ever built - Fetch, analyze, visualize, and optimize your development journey with comprehensive insights powered by AI.

🚀 Features

Core Analytics

Complete GitHub Profile Analysis - Deep insights into your development patterns
Repository Analytics - DevOps maturity, code quality, and community health metrics
AI-Powered Insights - GPT-4 analysis of code quality, security, and career recommendations
Real-time Data Collection - Live GitHub API integration with graceful degradation

Advanced Capabilities

Unified Refresh Endpoint - Update all user data in one request (POST /refresh/{username})
Automatic Scheduling - Configurable daily/weekly/monthly data updates
Comprehensive Error Handling - Partial success support with detailed reporting
JWT Authentication - Secure API access with GitHub token validation

Developer Experience

OpenAPI Documentation - Complete API specification with interactive docs
TypeScript Strict Mode - Full type safety and modern development practices
Comprehensive Logging - Detailed audit trail for debugging and monitoring
Rate Limiting - Respects GitHub API limits with intelligent throttling

📋 Quick Start

Prerequisites

Node.js >= 18.14.0
MongoDB (local or cloud)
GitHub Classic Token with required scopes (repo, user:email, read:user, read:org, read:packages, admin:repo_hook

Installation

# Clone the repository
git clone https://github.com/usernamap/gh-insight-engine.git
cd gh-insight-engine

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Initialize database
npm run db:push

# Start development server
npm run dev

Environment Configuration

# Database
DATABASE_URL=mongodb://localhost:27017/github_insight_engine

# GitHub API
GH_TOKEN=your_github_classic_token
GITHUB_USERNAME=your_username
GITHUB_FULL_NAME=Your Full Name

# OpenAI (for AI analysis)
OPENAI_API_KEY=your_openai_api_key

# Server
PORT=3000
NODE_ENV=development

# JWT Security
JWT_SECRET=your_jwt_secret

# Automatic Scheduling (Optional)
SCHEDULE_ENABLED=false
SCHEDULE_FREQUENCY=weekly
SCHEDULE_TIME=02:00
SCHEDULE_TIMEZONE=Europe/Paris
SCHEDULE_AUTH_TOKEN=

🔧 API Usage

Authentication

# Login with GitHub token
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "octocat",
    "fullName": "The Octocat",
    "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxx"
  }'

Complete Data Refresh

# Refresh all user data in one request
curl -X POST http://localhost:3000/api/refresh/octocat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Individual Operations

# Collect user profile
curl -X POST http://localhost:3000/api/users/octocat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Collect repositories
curl -X POST http://localhost:3000/api/repositories/octocat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Run AI analysis
curl -X POST http://localhost:3000/api/ai/octocat \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

📊 API Endpoints

Core Operations

POST /api/auth/login - GitHub token authentication
POST /api/refresh/{username} - Complete data refresh (NEW)
POST /api/users/{username} - Collect user profile
POST /api/repositories/{username} - Collect repositories
POST /api/ai/{username} - Run AI analysis

Data Retrieval

GET /api/users/{username} - Get user profile
GET /api/repositories/{username} - Get repositories with analytics
GET /api/summary/{username} - Get comprehensive developer summary
GET /api/ai/{username} - Get AI analysis results

System

GET /api/health - Health check
GET /api/ping - Connectivity test
GET /api/ai/status - AI service status

Automatic Scheduling

The application includes an automatic scheduling system that can update user data at configurable intervals without manual intervention.

Configuration

Enable automatic scheduling by setting these environment variables:

# Enable automatic scheduling
SCHEDULE_ENABLED=true

# Scheduling frequency (daily, weekly, monthly)
SCHEDULE_FREQUENCY=weekly

# Execution time in 24h format
SCHEDULE_TIME=02:00

# Timezone for execution
SCHEDULE_TIMEZONE=Europe/Paris

# Required user information
GITHUB_USERNAME=your_github_username
GITHUB_FULL_NAME=Your Full Name
GH_TOKEN=your_github_classic_token

How It Works

The scheduling service automatically:

Retrieves Authentication Tokens: Calls POST /auth/login to get a valid JWT token
Manages Token Expiration: Automatically renews tokens when they expire (24h default)
Executes Scheduled Updates: Calls POST /api/refresh/{username} at the configured intervals
Handles Errors Gracefully: Logs failures and continues operation

Features

Automatic Token Management: No manual token configuration required
Flexible Scheduling: Daily, weekly, or monthly updates
Timezone Support: Configurable timezone for execution
Error Handling: Robust error handling with detailed logging
Status Monitoring: Check scheduling status via service methods

Example Usage

import { SchedulingService } from '@/services/SchedulingService';

// Get scheduling status
const status = SchedulingService.getInstance().getStatus();
console.log('Scheduling enabled:', status.enabled);
console.log('Next run:', status.nextRun);

// Test configuration immediately
const success = await SchedulingService.getInstance().testConfiguration();

Security

Tokens are automatically retrieved and managed
No manual token storage required
Automatic token renewal prevents expiration issues
All operations are logged for audit purposes

🏗️ Architecture

GitHub API → Data Collection → MongoDB Storage → AI Analysis → API Response
     ↓              ↓              ↓              ↓              ↓
  Rate Limiting  Error Handling  Data Models  OpenAI GPT-4  JWT Auth

Key Components

GitHubService - Handles all GitHub API interactions
AIAnalysisService - OpenAI GPT-4 integration for insights
SchedulingService - Automatic data refresh management
RefreshController - Unified endpoint for complete data updates

🧪 Development

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

# Build for production
npm run build

# Start production server
npm start

📚 Documentation

API Documentation: http://localhost:3000/ (interactive OpenAPI docs)
OpenAPI Spec: openapi.yaml
Technical Documentation: docs/README.md
Contributing Guide: CONTRIBUTING.md
Code of Conduct: CODE_OF_CONDUCT.md
Security Policy: SECURITY.md
Changelog: CHANGELOG.md

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for detailed information on:

Setting up your development environment
Code style and conventions
Testing guidelines
Pull request process
Release procedures

For quick start:

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

📄 License

MIT License - see LICENSE for details.

🆘 Support

Issues: GitHub Issues
Documentation: API Docs
Discussions: GitHub Discussions

Built with ❤️ for the developer community

❤️ Donation Link ❤️