📊 Gitlytics

A full-stack GitHub analytics dashboard that connects to your GitHub account via OAuth, fetches repository and collaboration data through the GitHub API, and visualizes meaningful metrics on an interactive frontend.

Made by Pratham Sorte

---

📌 Table of Contents

• About
• Features
• Tech Stack
• Project Structure
• Architecture
• Installation & Setup
• Environment Variables
• Running with Docker
• API Overview
• Contributing
• Author
• License

---

📖 About

Gitlytics is a full-stack web application built to give developers and teams a deeper look into their GitHub collaboration patterns. By authenticating with GitHub OAuth, the app fetches data from the GitHub API and surfaces it as clear, interactive charts and metrics on a React-powered dashboard.

The backend is powered by Flask with Celery for async task processing, PostgreSQL for persistent storage, and Redis as a message broker. Everything is containerized with Docker Compose for easy local development and deployment.

---

✨ Features

• 🔐 GitHub OAuth authentication — secure login with your GitHub account
• 📡 GitHub API integration — pulls repository, commit, and contributor data
• 📈 Collaboration metrics visualization — charts showing contribution patterns across repositories
• ⚙️ Async task processing — Celery workers handle heavy API calls in the background
• 🗄️ PostgreSQL database — persists user data, repo data, and analytics
• 🔴 Redis — message broker for Celery task queue
• 🐳 Dockerized — one command to spin up the entire stack
• ⚛️ React SPA — fast, responsive frontend consuming a REST API

---

🛠️ Tech Stack

Layer	Technology
Backend	Python, Flask
Frontend	React (JavaScript)
Database	PostgreSQL
Task Queue	Celery + Redis
Auth	GitHub OAuth 2.0
Containerization	Docker, Docker Compose
API	GitHub REST API

Language breakdown: Python 71% · JavaScript 24% · Dockerfile 3% · HTML 2%

---

📁 Project Structure

Gitlytics/
│
├── backend/                  # Flask REST API
│   ├── app/
│   │   ├── routes/           # API endpoints
│   │   ├── models/           # SQLAlchemy database models
│   │   ├── tasks/            # Celery async tasks (GitHub API fetching)
│   │   ├── auth/             # GitHub OAuth logic
│   │   └── utils/            # Helper functions
│   ├── requirements.txt      # Python dependencies
│   └── Dockerfile
│
├── frontend/                 # React Single Page Application
│   ├── src/
│   │   ├── components/       # UI components
│   │   ├── pages/            # Route pages
│   │   └── services/         # API service calls
│   ├── package.json
│   └── Dockerfile
│
├── docker-compose.yml        # Orchestrates all services
├── .gitignore
└── README.md

---

🏗️ Architecture

User Browser
     │
     ▼
 React SPA (frontend)
     │  REST API calls
     ▼
 Flask API (backend)
     │              │
     ▼              ▼
PostgreSQL DB    Celery Worker
                     │
                   Redis
                  (broker)
                     │
                     ▼
              GitHub REST API

• The React frontend handles UI and communicates with the Flask backend via REST API.
• GitHub OAuth is managed by the backend — it redirects users to GitHub and exchanges tokens.
• Celery workers pick up async jobs (like fetching large amounts of GitHub data) from the Redis queue.
• Fetched data is stored and queried from PostgreSQL.

---

⚙️ Installation & Setup

Prerequisites

• Docker & Docker Compose installed
• A GitHub OAuth App (create one here)

1. Clone the repository

git clone https://github.com/prathaaaaaaam/Gitlytics.git
cd Gitlytics

2. Configure environment variables

Copy and fill in your credentials (see Environment Variables section below):

cp backend/.env.example backend/.env

3. Run with Docker Compose

docker-compose up --build

This starts:

• Flask API on http://localhost:5000
• React frontend on http://localhost:3000
• PostgreSQL on port 5432
• Redis on port 6379
• Celery worker (background)

---

🔑 Environment Variables

Create a .env file in the backend/ directory with the following:

# Flask
FLASK_ENV=development
SECRET_KEY=your_secret_key_here

# GitHub OAuth
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_CALLBACK_URL=http://localhost:5000/auth/callback

# PostgreSQL
DATABASE_URL=postgresql://user:password@db:5432/gitlytics

# Redis / Celery
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0

⚠️ Never commit real credentials. All values above are placeholders — replace them with your own.

---

🐳 Running with Docker

Start all services

docker-compose up --build

Run database migrations

After the containers are up, run migrations inside the backend container:

docker exec -it gitlytics_backend_1 bash
flask db upgrade

Stop all services

docker-compose down

View logs

docker-compose logs -f backend
docker-compose logs -f worker

---

🔌 API Overview

Method	Endpoint	Description
GET	/auth/login	Redirects to GitHub OAuth
GET	/auth/callback	Handles OAuth callback
GET	/api/user	Returns authenticated user info
GET	/api/repos	Returns user's repositories
GET	/api/repos/:id/metrics	Returns collaboration metrics for a repo
POST	/api/repos/:id/sync	Triggers async Celery task to sync repo data

---

🤝 Contributing

Pull requests are welcome! To contribute:

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

---

👨‍💻 Author

Pratham Sorte

• GitHub: @prathaaaaaaam

---

📄 License

This project is open source. Feel free to use, modify, and distribute it.

---

🙌 Acknowledgements

• Flask — lightweight Python web framework
• Celery — distributed task queue
• React — frontend library
• GitHub REST API — data source
• Docker — containerization platform