DevFlow - GitHub Project Dashboard

📋 Table of Contents

Overview
Key Features
Technology Stack
Project Structure
Getting Started
Deployment
API Development Status
Documentation
Contributing

🎯 Overview

DevFlow is a comprehensive SaaS platform that provides a unified dashboard for managing GitHub issues across multiple repositories. It enhances GitHub's native interface with advanced project management features, custom workflows, analytics, and cross-platform accessibility.

What Problem Does It Solve?

Multi-Repository Management: Developers working on multiple projects struggle to track issues across different repositories
Custom Workflows: GitHub's native interface lacks flexibility for custom categorization and workflows
Unified Dashboard: No single view to see all your issues and tasks in one place
Team Collaboration: Limited project management features for teams
Analytics: Minimal insights into project progress and team productivity

Target Users

👨‍💻 Individual Developers - Managing personal projects
👥 Development Teams - Collaborative project management
📊 Project Managers - Oversight and analytics
🎯 Team Leads - Task assignment and tracking

✅ What's Implemented

DevFlow is currently in active development with core functionality ready!

🎉 Completed Features

✅ Authentication System (100%)

GitHub OAuth 2.0 integration
JWT token-based authentication
Secure user session management
Access token refresh mechanism

✅ Repository Management (100%)

Add/remove repositories from GitHub
Multi-repository dashboard
Sync repositories with GitHub
Webhook configuration
Custom grouping and metadata

✅ Issue Management (100%)

Create, read, update, and close issues
Advanced filtering (by status, priority, labels, assignees, repository)
Bulk operations on multiple issues
Assign/unassign team members
Label management
Comment system (CRUD operations)
Direct GitHub synchronization
Pagination support

✅ Labels Management (100%)

Create, update and delete labels per repository
Sync labels directly from GitHub
Full label metadata (name, color, description)

✅ Custom Categories (100%)

Create and manage custom issue categories per user
Assign/remove categories on any issue
Conflict detection (duplicate names)
Issue count per category

✅ Saved Views & Filters (100%)

Save custom filter combinations as named views
Mark a view as default
Apply a view to instantly retrieve matching issues
Full CRUD (create, update, delete views)

✅ Analytics Dashboard (100%)

Dashboard overview: totals, priority breakdown, close rate
Issues grouped by state and custom workflow status
Issues grouped by repository
Daily timeline of created vs closed issues (7d / 30d / 90d / 1y)
Assignee workload distribution
Completion rate overall and per repository

✅ Notifications System (100%)

List notifications with filters (type, read status, pagination)
Get single notification details
Get unread notification count
Mark individual notification as read
Mark all notifications as read
Delete individual notification
Delete all read notifications (bulk cleanup)

✅ Additional Features (100%)

Milestones: create and list milestones per repository
Settings: view and update user profile settings
Activity Log: paginated timeline of user actions
Global Search: full-text search across issues and repositories
Data Export: download issues, repositories, or milestones as CSV or JSON
Bulk Actions: close, reopen, label, milestone or prioritize multiple issues at once
Teams: create teams and list members
Webhooks: register GitHub webhooks per repository
Health Check: live database connectivity and uptime report

✅ Developer Experience

🔥 Interactive Swagger UI at /api-docs
📋 Complete OpenAPI 3.0 specification
📦 Postman collection with 72 endpoints
📖 Comprehensive documentation
🛡️ Input validation and error handling
🔒 Security best practices (Helmet, CORS, Rate Limiting)

📊 Current Status

72 API endpoints implemented and fully functional
18 database tables with complete relationships
9 major API categories completed (Auth, Repos, Issues, Labels, Categories, Views, Analytics, Notifications, Additional Features)
Swagger documentation for all endpoints
Production-ready backend infrastructure

🚧 Coming Next

React Web Frontend
Flutter Mobile App
Real-time updates (WebSockets)
Unit & integration test suite

✨ Key Features

Core Features

✅ GitHub OAuth Authentication - Secure login via GitHub
📦 Multi-Repository Integration - Connect and manage multiple repos
🎯 Unified Issue Dashboard - All issues in one place
🏷️ Custom Labels & Categories - Organize issues your way
💬 Comment Management - Threaded discussions
🔍 Advanced Filtering & Saved Views - Find and save issue filters
📊 Analytics & Insights - Track progress and productivity
🔔 Smart Notifications - Stay updated on important changes
🏁 Milestones - Group issues into release milestones
🔎 Global Search - Search issues and repositories instantly
📤 Data Export - Download data as CSV or JSON
⚡ Bulk Actions - Close, label, or prioritize many issues at once
👥 Teams - Create teams and manage members
🌓 Dark/Light Mode - Comfortable viewing experience

Platform Support

🌐 Web Application - React-based responsive UI
📱 Mobile Apps - Flutter for iOS & Android
🔌 RESTful API - Node.js backend with Express

🛠️ Technology Stack

Backend

Runtime: Node.js 20+
Framework: Express.js 5.x
Language: TypeScript 5.x
Database: PostgreSQL 18
ORM: Prisma 5.22+
Authentication: Passport.js + JWT + GitHub OAuth 2.0
Security: Helmet, CORS, Rate Limiting, Express Validator
API Documentation: Swagger/OpenAPI 3.0 (swagger-jsdoc, swagger-ui-express)
HTTP Client: Axios 1.13+ for GitHub API integration

Frontend (Planned)

Web: React 18+ with TypeScript
Mobile: Flutter 3.x with Dart
State Management: Redux Toolkit / Riverpod
UI Framework: Material-UI / Tailwind CSS

DevOps & Infrastructure

CI/CD: GitHub Actions (3-job pipeline: test → build → deploy)
Containerization: Docker + Docker Compose
Container Registry: GitHub Container Registry (GHCR)
Backend Hosting: AWS EC2 (t3.micro, eu-north-1)
Database Hosting: AWS RDS PostgreSQL 17 (eu-north-1)
Frontend Hosting: Cloudflare Pages (coming soon)
Package Manager: npm
Development: Nodemon, ts-node
API Testing: Swagger UI, Postman

📁 Project Structure

DevFlow/
├── backend/                    # Backend API server
│   ├── src/
│   │   ├── index.ts                    # Entry point
│   │   ├── controllers/               # Request handlers (9 files)
│   │   │   └── additional.controller.ts
│   │   ├── services/                  # Business logic (9 files)
│   │   │   └── additional.service.ts
│   │   ├── models/                    # TypeScript type definitions (9 files)
│   │   │   └── additional.model.ts
│   │   ├── routes/                    # API route definitions (9 files)
│   │   │   └── additional.routes.ts
│   │   └── middleware/                # Auth, validation, error handling
│   ├── prisma/
│   │   └── schema.prisma              # Database schema (18 tables)
│   ├── package.json
│   └── tsconfig.json
├── docs/                       # Documentation files
│   ├── SRS_GitHub_Dashboard.md
│   ├── QUICK_START.md
│   ├── ROADMAP.md
│   └── SETUP_GUIDE.md
└── README.md                   # This file

🚀 Getting Started

Prerequisites

Node.js 18+ and npm
PostgreSQL 14+
GitHub Account (for OAuth setup)
Git for version control

Quick Setup

Clone the repository
```
git clone <repository-url>
cd DevFlow
```
Install dependencies
```
cd backend
npm install
```

Configure environment

cp .env.example .env
# Edit .env with your credentials

Setup database

# Create PostgreSQL database
createdb -U postgres devflow_db

# Run migrations
npm run prisma:migrate

Start development server
```
npm run dev
```
Access the application
- 🌐 Server: http://localhost:3001
- 🔥 Swagger UI: http://localhost:3001/api-docs
- 🏥 Health Check: http://localhost:3001/api/health

📖 For detailed setup instructions, see QUICK_START.md

🚢 Deployment

✅ Backend — Live on AWS EC2

Production URL: http://16.16.218.19:3001

Resource	Details
Server	AWS EC2 t3.micro (eu-north-1)
Database	AWS RDS PostgreSQL 17 (eu-north-1)
Container	Docker via GHCR (`ghcr.io/shalin-shah-2002/devflow-backend:latest`)
Swagger UI	http://16.16.218.19:3001/api-docs
API Spec	http://16.16.218.19:3001/api-docs.json

CI/CD Pipeline (GitHub Actions)

Every push to main that touches backend/ triggers a 3-job pipeline:

Job 1: api-tests  (~2 min)
├── Spins up a real PostgreSQL container
├── Runs Prisma migrations
├── Builds and starts the backend
├── Seeds test data
└── Hits all 66 Swagger endpoints — must pass before proceeding

Job 2: build-and-push-image  (~3 min)
├── Builds multi-stage Docker image (node:20-slim)
│   ├── Stage 1: compile TypeScript, generate Prisma client, pre-build swagger.json
│   └── Stage 2: production-only deps, ~200MB lean image
└── Pushes to GHCR with :latest and :sha tags

Job 3: deploy-ec2  (~1 min)
├── SCP docker-compose.yml to EC2
├── SSH: write .env from GitHub secret
├── docker compose pull → docker compose up -d
└── Container runs: prisma migrate deploy && node dist/index.js

Required GitHub Secrets

Secret	Value
`EC2_HOST`	`16.16.218.19`
`EC2_USER`	`ec2-user`
`EC2_SSH_KEY`	EC2 private key (PEM format)
`BACKEND_ENV_FILE`	Full `.env` contents (DB URL, JWT secret, GitHub OAuth, etc.)

Re-deploy manually

Go to GitHub → Actions → Backend CI/CD → Run workflow to trigger without a push.

🔜 Frontend — Cloudflare Pages (coming soon)

Frontend (React + Vite) will be deployed to Cloudflare Pages. Once live, update the FRONTEND_URL in the BACKEND_ENV_FILE GitHub secret and update the GitHub OAuth app callback URL.

🧪 Testing the API

Option 1: Swagger UI (Recommended)

Start the server: npm run dev
Open http://localhost:3001/api-docs in your browser
Click "Authorize" and enter your JWT token
Try out any endpoint with the "Try it out" button

Option 2: Postman

Import the collection: backend/Docs/Postman_Collection.json
Set up environment variables (base_url, access_token)
Test all 72 endpoints with pre-configured requests

Option 3: cURL

# Health check
curl http://localhost:3001/api/health

# Get current user (requires auth)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3001/api/auth/me

# List issues
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3001/api/issues?state=open&page=1&limit=20

🔄 API Development Status

Track the implementation progress of all API endpoints across 10 categories.

API Categories Checklist

🔐 1. Authentication APIs (5 endpoints)

POST /api/auth/github - Initiate GitHub OAuth
GET /api/auth/github/callback - OAuth callback handler
GET /api/auth/me - Get current user profile
POST /api/auth/refresh - Refresh access token
POST /api/auth/logout - Logout user

📦 2. Repository APIs (7 endpoints)

GET /api/repositories - List all repositories
POST /api/repositories - Add repository
GET /api/repositories/:id - Get repository details
PATCH /api/repositories/:id - Update repository
DELETE /api/repositories/:id - Remove repository
POST /api/repositories/:id/sync - Sync with GitHub
POST /api/repositories/:id/webhook - Setup GitHub webhook

🎯 3. Issue APIs (12 endpoints)

🏷️ 4. Label APIs (6 endpoints)

GET /api/labels - List all labels
POST /api/labels - Create label
GET /api/labels/:id - Get label details
PUT /api/labels/:id - Update label
DELETE /api/labels/:id - Delete label
POST /api/labels/sync/:repoId - Sync labels from GitHub

💬 5. Comment APIs (6 endpoints) — ✅ Integrated into Issue APIs

GET /api/issues/:id/comments - List all comments for an issue
POST /api/issues/:id/comments - Add comment (syncs to GitHub)
PATCH /api/issues/:id/comments/:commentId - Edit comment (syncs to GitHub)
DELETE /api/issues/:id/comments/:commentId - Delete comment (syncs to GitHub)
POST /api/issues/:id/assign - Assign/unassign users (syncs to GitHub)
POST /api/issues/:id/labels - Add/remove labels (syncs to GitHub)

📂 6. Category APIs (6 endpoints)

GET /api/categories - List all categories (per user)
POST /api/categories - Create category
PATCH /api/categories/:id - Update category name/color
DELETE /api/categories/:id - Delete category
POST /api/issues/:id/categories - Assign categories to issue
DELETE /api/issues/:id/categories/:categoryId - Remove category from issue

🔍 7. Filter & Views APIs (5 endpoints)

GET /api/views - List all saved views/filters
POST /api/views - Create custom view/filter
PATCH /api/views/:id - Update view/filter
DELETE /api/views/:id - Delete view/filter
POST /api/views/:id/apply - Apply view (get filtered issues)

📊 8. Analytics APIs (6 endpoints)

GET /api/analytics/dashboard - Dashboard overview (totals, priority breakdown, close rate)
GET /api/analytics/issues-by-status - Issues grouped by state & custom status
GET /api/analytics/issues-by-repo - Issues grouped by repository
GET /api/analytics/issues-over-time - Daily timeline of created vs closed (?period=7d|30d|90d|1y)
GET /api/analytics/assignee-workload - Open/closed counts per assignee
GET /api/analytics/completion-rate - Completion rate overall and per repository

🔔 9. Notification APIs (7 endpoints)

GET /api/notifications - List notifications (with filters: type, isRead, pagination)
GET /api/notifications/unread-count - Get unread notification count
GET /api/notifications/:id - Get notification details
PATCH /api/notifications/:id/read - Mark as read
PATCH /api/notifications/read-all - Mark all notifications as read
DELETE /api/notifications/:id - Delete notification
DELETE /api/notifications/read - Delete all read notifications (bulk cleanup)

🎨 10. Additional Features (12 endpoints)

📈 Progress Summary

Category	Total	Completed	Percentage
Authentication	5	5	100% ✅
Repositories	7	7	100% ✅
Issues	12	12	100% ✅
Labels	6	6	100% ✅
Comments	6	6	100% ✅
Categories	6	6	100% ✅
Filters & Views	5	5	100% ✅
Analytics	6	6	100% ✅
Notifications	7	7	100% ✅
Additional	12	12	100% ✅
TOTAL	72	72	100%

📚 Documentation

📖 Software Requirements Specification (SRS) - Complete feature specifications
⚡ Quick Start Guide - Get up and running in minutes
🗺️ Project Roadmap - Implementation phases and timeline
🔧 Setup Guide - Detailed setup instructions
🔌 API Documentation - Complete API reference (72 endpoints)
🔥 Swagger UI - Interactive API testing (when server is running)
📋 OpenAPI Spec - Machine-readable API specification
📮 Postman Collection - Ready-to-use API collection
🗄️ Database Schema - Database design and relationships
💾 Database Setup - PostgreSQL configuration
🤝 Contributing Guide - How to contribute to the project
📜 Code of Conduct - Community guidelines

🏗️ Development Roadmap

✅ Phase 0: Setup (COMPLETED)

✅ Phase 1: Core Backend (COMPLETED)

Authentication system (GitHub OAuth + JWT)
Repository management (7 endpoints)
Issue CRUD operations (12 endpoints)
Comment management (integrated with issues)
GitHub API integration
Validation & error handling middleware
Swagger/OpenAPI documentation

✅ Phase 2: Advanced Features (COMPLETED)

🚧 Phase 3: Frontend Development (IN PROGRESS)

React web application (in progress)
Flutter mobile app
UI/UX implementation
State management

✅ Phase 3: Backend Deployment (COMPLETED)

Dockerized backend with multi-stage build
AWS EC2 instance (t3.micro, eu-north-1)
AWS RDS PostgreSQL 17
GitHub Container Registry (GHCR) for Docker images
GitHub Actions CI/CD pipeline (test → build → deploy)
Automated API smoke tests (66 endpoints) on every push
Pre-generated Swagger spec (served from container)
Production Swagger UI live at http://16.16.218.19:3001/api-docs

🚧 Phase 4: Frontend Deployment (IN PROGRESS)

React + Vite frontend build
Deploy to Cloudflare Pages
Configure production API URL
Update GitHub OAuth callback URL
CI/CD for frontend (auto-deploy on push)

🎯 Phase 5: Production Polish (PLANNED)

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

🚀 Quick Start for Contributors

Read the Contributing Guide - CONTRIBUTING.md
Check the Code of Conduct - CODE_OF_CONDUCT.md
Look for Good First Issues - Tagged with good first issue label

📝 How to Contribute

Fork the repository
Clone your fork: git clone https://github.com/YOUR_USERNAME/devflow.git
Create a feature branch: git checkout -b feature/AmazingFeature
Make your changes
Test thoroughly
Commit with clear messages: git commit -m 'feat: add amazing feature'
Push to your fork: git push origin feature/AmazingFeature
Open a Pull Request

💬 Get in Touch

Want to contribute or discuss ideas?

📧 Email: 2002shalin@gmail.com
🐛 Report Issues: GitHub Issues
💡 Feature Requests: GitHub Issues
🐞 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions

🏷️ Ways to Contribute

Report Bugs - Found something broken? Let us know!
Suggest Features - Have ideas? We'd love to hear them!
Write Code - Pick up issues labeled help wanted or good first issue
Improve Docs - Help make our documentation better
Review PRs - Help review and test pull requests
Spread the Word - Star ⭐ the repo and share with others

✅ Development Guidelines

Follow TypeScript best practices
Write clean, documented code
Add tests for new features
Update documentation as needed
Follow our commit message conventions
Ensure all tests pass before submitting PR

For detailed guidelines, see CONTRIBUTING.md

📝 License

This project is licensed under the ISC License.

👨‍💻 Author

DevFlow Team

🙏 Acknowledgments

GitHub API for providing robust integration capabilities
Prisma for excellent ORM support
The open-source community for amazing tools and libraries

📞 Support

For questions, issues, or suggestions:

📧 Email: 2002shalin@gmail.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Documentation: Check our docs and guides

⭐ Star this project if you find it helpful!

Made with ❤️ for developers, by developers

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
Frontend		Frontend
backend		backend
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
DevFlow_API_Postman_Collection.json		DevFlow_API_Postman_Collection.json
QUICK_START.md		QUICK_START.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SETUP_GUIDE.md		SETUP_GUIDE.md
SRS_GitHub_Dashboard.md		SRS_GitHub_Dashboard.md
package-lock.json		package-lock.json

Latest commit

History

Folders and files

Repository files navigation