GitTeamPulse 🚀

A beautiful, real-time GitHub team analytics dashboard that provides insights into pull requests, releases, branches, and developer activity. Built with React, TypeScript, Express, and MongoDB.

✨ Features

• 📊 Dashboard Metrics: Real-time view of open PRs, stale PRs, branches, and stale branches
• 👥 Top Contributors: Weekly leaderboard showing top 3 contributors with merged PRs
• 🚀 Release Tracking: Monitor releases and tags across your repositories
• 🌿 Branch Management: Track active and stale branches with last commit information
• 📈 Analytics Charts: Visual charts for PRs, releases, and time-to-close metrics
• 🔄 Auto-Refresh: Smart caching with 15-minute TTL and manual refresh option
• 🌓 Dark Mode: Beautiful light and dark themes
• 🔐 Authentication: Secure JWT-based authentication system
• 📱 Responsive Design: Works seamlessly on desktop and mobile devices

🏗️ Architecture

GitTeamPulse/
├── client/              # React frontend (Vite + TypeScript)
│   ├── src/
│   │   ├── api/        # API client functions
│   │   ├── components/ # React components
│   │   ├── pages/      # Page components
│   │   └── types/      # TypeScript types
│   └── package.json
├── server/             # Express backend (TypeScript)
│   ├── config/        # Database configuration
│   ├── models/        # Mongoose models
│   ├── routes/        # API routes
│   ├── services/      # Business logic
│   └── utils/         # Utility functions
├── shared/            # Shared types and constants
└── package.json       # Root package

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• MongoDB (v5 or higher)
• GitHub Personal Access Token with repo and read:org permissions

Installation

1. Clone the repository

   git clone <repository-url>
   cd GitTeamPulse

2. Install dependencies

   npm install

3. Set up environment variables

   Create a .env file in the server/ directory:

   cd server
   cp .env.example .env

   Edit server/.env with your configuration:

   PORT=3000
   DATABASE_URL=mongodb://localhost:27017/GitTeamPulse
   JWT_SECRET=your-super-secret-jwt-key-change-this
   REFRESH_TOKEN_SECRET=your-super-secret-refresh-token-key-change-this

4. Start MongoDB

   # On macOS with Homebrew
   brew services start mongodb-community
   
   # On Linux with systemd
   sudo systemctl start mongod
   
   # Or run directly
   mongod --dbpath /path/to/data/directory

5. Start the application

   # From the root directory
   npm start

   This will start both the frontend (port 5173) and backend (port 3000) concurrently.

6. Access the application

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:3000

First Time Setup

1. Register a new account

   • Navigate to http://localhost:5173/register
   • Create your account with email and password

2. Configure GitHub Integration

   • Go to Settings page
   • Enter your GitHub Personal Access Token
     • Create one at: https://github.com/settings/tokens/new
     • Required scopes: repo, read:org
   • Enter your GitHub organization name
   • Add repositories you want to track
   • Click "Save Settings"

3. Explore the Dashboard

   • Home: View metrics, releases, and top contributors
   • Branches: See active and stale branches
   • Charts: Analyze trends with visual charts

🔧 Development

Project Structure

Frontend (client/)

• Built with React 18 + TypeScript
• Vite for fast development and building
• Tailwind CSS + shadcn/ui components
• React Router for navigation
• Recharts for data visualization

Backend (server/)

• Express.js with TypeScript
• MongoDB with Mongoose ODM
• JWT authentication
• GitHub API integration via Octokit
• Smart caching system

Development Commands

# Start development servers
npm start

# Run linting
npm run lint

# Build for production
npm run build

# Run tests (if configured)
npm test

Development Scripts

Client (cd client/)

npm run dev      # Start Vite dev server
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint

Server (cd server/)

npm run dev      # Start development server with hot reload
npm run build    # Build TypeScript
npm run start    # Start production server
npm run lint     # Run ESLint

📚 API Documentation

Authentication Endpoints

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/logout - Logout user
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/me - Get current user

GitHub Endpoints

All GitHub endpoints require authentication.

• GET /api/github/settings - Get GitHub settings
• POST /api/github/settings - Save GitHub settings
• GET /api/github/metrics - Get dashboard metrics
• GET /api/github/activity/weekly - Get weekly activity
• GET /api/github/branches - Get branches
• GET /api/github/charts/merged-prs - Get merged PRs chart data
• GET /api/github/charts/releases - Get releases chart data
• GET /api/github/charts/closed-prs - Get closed PRs chart data
• GET /api/github/charts/avg-time-to-close - Get average time to close chart
• POST /api/github/refresh - Clear cache and refresh data

🎨 Features in Detail

Dashboard Metrics

Track key metrics at a glance:

• Open PRs: Total currently open pull requests
• Stale PRs: PRs open for more than 7 days (with draft/active breakdown)
• Total Branches: All branches across tracked repositories
• Stale Branches: Branches with last commit older than 7 days

Weekly Activity

View activity organized by week with:

• Number of releases (with 🚀 rocket icon)
• Top 3 contributors with medal rankings (🥇🥈🥉)
• Expandable details showing all contributors
• Merged and closed PR counts

Branch Management

Monitor your branches with:

• Active Branches: Last commit within 7 days
• Stale Branches: Highlighted branches needing attention
• Developer avatars and names
• Time since last commit
• Direct links to GitHub

Analytics Charts

Visualize trends over 12 weeks:

• Merged PRs per week
• Releases per week
• Closed (not merged) PRs per week
• Average time to close PRs

🔒 Security

• JWT-based authentication with access and refresh tokens
• Bcrypt password hashing
• GitHub tokens stored securely and masked in responses
• Environment variables for sensitive configuration
• CORS protection
• Request validation and error handling

🎯 Tech Stack

Frontend

• React 18
• TypeScript
• Vite
• Tailwind CSS
• shadcn/ui
• React Router
• Recharts
• Axios
• date-fns

Backend

• Node.js
• Express
• TypeScript
• MongoDB
• Mongoose
• JWT
• Octokit (GitHub API)
• Bcrypt

📝 Environment Variables

Server (server/.env)

Variable	Description	Required
PORT	Server port number	Yes
DATABASE_URL	MongoDB connection string	Yes
JWT_SECRET	Secret for JWT access tokens	Yes
REFRESH_TOKEN_SECRET	Secret for JWT refresh tokens	Yes

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with shadcn/ui for beautiful UI components
• Icons from Lucide Icons
• Charts powered by Recharts
• GitHub API integration via Octokit

📧 Support

If you have any questions or run into issues, please open an issue on GitHub.

---

Made with ❤️ using Pythagora