🚀 MergeShip - Gamified Open Source Contribution Platform

Bridge the gap between maintainers and contributors with AI-powered trust layers

MergeShip is the first dual-sided platform that professionalizes open-source contribution through structured learning paths, hierarchical peer mentorship, and intelligent organization tools—making open source sustainable for both sides.

🔗 View Live Demo | 📖 Read the Documentation

🎯 The Problem We Solve

For Maintainers 😰

46% feel overwhelmed (GitHub 2023 Survey)
Drowning in low-quality PRs and AI-generated noise
No way to identify skilled contributors quickly
Spending hours on triage instead of building

For Contributors 😕

Don't know where to start or what to contribute
PRs get ignored or rejected without feedback
No structured path from beginner to expert
Lack of mentorship and community support

💡 The Solution

MergeShip creates a reputation layer on top of GitHub — like LinkedIn professionalized networking, we're professionalizing open-source contribution.

For Contributors 🎮

4-Level Trust System: Beginner → Intermediate → Advanced → Expert → Mentor
Gamified Learning: 5-Day Foundational Course → XP → Badges → Streaks
AI-Powered Issue Matching: Groq AI classifies issues by difficulty (Easy/Medium/Hard)
Hierarchical Peer Mentorship: Level 2 mentors Level 1, Level 3 mentors Level 2, etc.
PR Pre-Verification: Mentors review before maintainers see it
Live Leaderboard: Compete with real contributors, track your rank

For Maintainers 🛡️

Command Center Dashboard: Unified view of issues, PRs, discussions
Trust-Tier PR Queue: See "L3-Verified by Mentor" badges
AI-Assisted Triage: Groq AI auto-classifies and prioritizes
Org Analytics: Track team workload, PR velocity, repo health
GitHub App Integration: 5-step onboarding wizard

✨ Key Features

🎓 Learning & Progression

5-Day Foundational Course: Git basics, GitHub workflow, PR quality, open-source culture
Level-Based Access: Unlock harder issues as you level up
XP & Achievements: Earn points for contributions, claim badges
Daily Streaks: Maintain momentum with daily contribution goals

🤝 Community & Mentorship

Peer Mentorship Hub: Get paired with mentors based on skill level
Direct Messaging: Chat with mentors and contributors
Skill-Based Matching: Find mentors in your tech stack
Review Feedback: Learn from detailed PR reviews

🔍 Issue Explorer (Live)

Real GitHub Issues: Fetches from ANY public repo
AI Classification: Groq llama-3.1-8b-instant categorizes difficulty
Smart Caching: 5-minute cache for performance
Level Gating: Only see issues you can handle
Rate Limit Handling: Graceful fallbacks for GitHub API limits

🏆 Leaderboard (Real-Time)

Live Rankings: Real MergeShip users ranked by XP
Your Percentile: See where you stand (Top X%)
Timeframe Toggle: This Month vs All Time
GitHub Avatars: Real profile pictures from GitHub

🛠️ Maintainer Tools

Org Feed: Aggregated view of all repos
Triage Queue: Priority-sorted with AI labels
Analytics Dashboard: Charts for velocity, health, team load
5-Step Onboarding: GitHub App-style wizard for setup

🏗️ Tech Stack

Frontend

Next.js 14 (App Router)
React (Client & Server Components)
Tailwind CSS + shadcn/ui
Framer Motion (Animations)
Lucide Icons

Backend

Next.js Server Actions
Appwrite (Auth, Database, Real-time)
Node.js

AI & APIs

Groq AI (llama-3.1-8b-instant) - Issue classification
GitHub API - Issue fetching, user data
Appwrite Cloud - User stats, leaderboard

Database

Appwrite Database (user_stats collection)
MongoDB (optional, for caching)

Deployment

Deployment: Vercel
Supervisor (Process management)
Docker (Containerized)

🚀 Getting Started

Prerequisites

Node.js 20+ and Yarn
Appwrite Cloud account
Groq API key
GitHub OAuth App

1. Clone the Repository

git clone https://github.com/nextgendev2029/MergeShip.git
cd MergeShip

2. Install Dependencies

cd app
yarn install

3. Environment Setup

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Required environment variables:

NEXT_PUBLIC_APPWRITE_ENDPOINT - Your Appwrite endpoint
NEXT_PUBLIC_APPWRITE_PROJECT_ID - Appwrite project ID
APPWRITE_API_KEY - Appwrite API key (server-side)
GROQ_API_KEY - Groq API key for AI classification
NEXT_PUBLIC_BASE_URL - Your app URL (e.g., http://localhost:3000)
MONGO_URL - MongoDB connection string (optional)

4. Appwrite Setup

Create Database & Collection:

Database ID: 69e12a90002821b7a144
Collection: user_stats

Attributes:
- githubHandle (string, required, indexed)
- statsJson (string, size 16000)
- heatmapJson (string, size 16000)
- lastSync (integer)

Configure OAuth:

Go to Appwrite Console → Auth → Settings
Enable GitHub OAuth
Add your GitHub OAuth App credentials
Set success URL: {YOUR_URL}/onboarding
Set failure URL: {YOUR_URL}/onboarding?auth=failed

5. Run Development Server

yarn dev

Open http://localhost:3000 in your browser.

6. Demo Mode (Testing)

Use demo mode to test without OAuth:

http://localhost:3000/onboarding?demo=gaearon&role=contributor
http://localhost:3000/onboarding?demo=gaearon&role=maintainer

📖 User Flows

Contributor Journey

1. Sign in with GitHub OAuth
2. Select "I am a Contributor"
3. AI analyzes your GitHub profile
4. Complete 5-Day Foundational Course (if new)
5. Dashboard unlocked → Start claiming issues
6. Earn XP → Level up → Unlock harder issues
7. Get mentorship from higher-level contributors
8. Climb the leaderboard

Maintainer Journey

1. Sign in with GitHub OAuth
2. Select "I am a Maintainer"
3. Complete 5-step onboarding wizard:
   - Connect GitHub
   - Select Organization
   - Choose Repositories
   - Review Permissions
   - Setup Complete
4. Access Command Center
5. Triage issues with AI assistance
6. Review PRs sorted by trust tier
7. View org analytics

🎮 Features Breakdown

Phase 1-3: Foundation

Landing page with feature showcase
GitHub OAuth integration
Role-based routing (Contributor/Maintainer)
Dashboard skeleton

Phase 4: Issue Explorer & Achievements

AI-powered issue recommendations
Personalized feed based on GitHub activity
Achievement system with badges

Phase 5: Maintainer Command Center

Triage dashboard with priority queues
Analytics with charts (Chart.js)
AI-assisted issue classification

Phase 6: Community & Leaderboards

Global and custom leaderboards (LIVE)
Portfolio generation
Community profiles

Phase 7: 4-Level Contributor System

Hierarchical progression (L1 → L5)
Peer mentorship hub
Direct messaging system
XP and level calculations

Phase 8: UX Improvements

Removed cross-role navigation confusion
Personalized repo feeds
Server action CORS fixes

Phase 9: Maintainer Onboarding Wizard

5-step GitHub App-style flow
Organization & repo selection
Permissions overview
Setup completion with confetti

Phase 10: Live Data Integration

Real GitHub Issues: Fetches from any public repo
AI Classification: Groq llama-3.1-8b-instant
Real Leaderboard: Appwrite users only (no mock data)
Caching: 5-minute TTL for performance

🔐 Authentication & Security

OAuth Provider: Appwrite (GitHub integration)
Session Management: httpOnly cookies (secure)
Logout: Properly deletes sessions + clears local data
Protected Routes: Auto-redirect logged-in users
No Token Exposure: All sensitive operations server-side
Environment Variables: All secrets in .env (not in code)

🎨 UI/UX Design

Design System

Dark Mode Only: #060611 base, #1E1826 cards
Semantic Colors:
- Purple (#A78BFA) - Contributor accent
- Cyan (#38BDF8) - Maintainer accent
- Green (#4ADE80) - Success
- Red (#EF4444) - Errors
Typography: Outfit (headings), Inter (body)
Components: shadcn/ui (Tailwind-based)
Animations: Framer Motion (smooth transitions)

UX Principles

Loading States: Skeletons, spinners, progress bars
Error States: Clear messages with retry options
Empty States: Helpful CTAs and guidance
Feedback: Success toasts, XP animations
Accessibility: Semantic HTML, keyboard navigation

📊 API Rate Limits

GitHub API

Unauthenticated: 60 requests/hour per IP
Authenticated: 5000 requests/hour (not implemented yet)
Handling: Graceful fallbacks, cache, error messages

Groq AI

Rate Limits: Subject to provider limits
Handling: Fallback to label-based classification
Batch Size: Max 15 issues per request

Appwrite

Database Queries: Optimized with .limit(100)
Session Cookies: httpOnly, secure
Real-time: Not used (polling for updates)

🧪 Testing

Manual Testing

✅ OAuth flow (contributor + maintainer)
✅ Issue Explorer with real repos
✅ AI classification (Groq)
✅ Leaderboard with real users
✅ Logout + session persistence
✅ Protected routes
✅ Settings page

Demo Mode

Use ?demo={githubHandle} to bypass OAuth:

/dashboard?demo=gaearon
/issues?demo=vercel
/onboarding?demo=torvalds&role=maintainer

Test Script

Run Appwrite connection test:

cd /app && node scripts/test-appwrite.js

📁 Project Structure

/app
├── app/
│   ├── page.js                     # Landing page (protected route)
│   ├── layout.js                   # Root layout
│   ├── onboarding/                 # Onboarding flow
│   │   ├── page.js                 # Role selection + OAuth
│   │   ├── actions.js              # Server actions (profile analysis)
│   │   └── MaintainerWizard.jsx    # 5-step wizard
│   ├── (contributor)/              # Contributor routes
│   │   ├── dashboard/              # Dashboard + actions
│   │   ├── issues/                 # Issue Explorer (LIVE)
│   │   ├── leaderboard/            # Leaderboard (LIVE)
│   │   ├── mentorship/             # Mentorship hub
│   │   ├── messages/               # Direct messaging
│   │   ├── portfolio/              # User portfolio
│   │   └── settings/               # Settings page
│   └── (maintainer)/               # Maintainer routes
│       └── maintainer/             # Command center + triage + analytics
├── components/
│   ├── layout/                     # Sidebars, Topbar
│   ├── dashboard/                  # Widgets, LevelBadge
│   └── auth/                       # Auth components
├── lib/
│   ├── appwrite.js                 # Client-side Appwrite
│   ├── appwrite-server.js          # Server-side Appwrite
│   ├── levels.js                   # Level calculations
│   └── utils.js                    # Utilities
├── scripts/
│   └── test-appwrite.js            # Appwrite test script
├── .env                            # Environment variables (gitignored)
├── .env.example                    # Example env file
└── package.json                    # Dependencies

🌟 Roadmap

Current Features (v1.0)

Coming Soon (v1.1)

Future (v2.0)

Multi-language support
Advanced analytics (ML insights)
Integration with CI/CD pipelines
Enterprise features (SSO, audit logs)
API for third-party integrations

💰 Business Model

Freemium Pricing

Contributors: Free tier, Pro at $5/month (priority support, custom badges)
Organizations:
- Small: $49/month (up to 10 repos)
- Growth: $149/month (up to 50 repos)
- Enterprise: Custom pricing

Revenue Streams

Pro Subscriptions: Premium features for contributors
Org Plans: Maintainer tooling for teams
API Access: Third-party integrations
White-label: Custom branding for enterprises

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow existing code style (ESLint + Prettier)
Add tests for new features
Update documentation
Keep commits atomic and descriptive

📄 License

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

🙏 Acknowledgments

GitHub for the amazing API
Groq AI for lightning-fast LLM inference
Appwrite for the backend platform
Next.js team for the incredible framework
shadcn for the beautiful UI components
Vercel for the deployment platform

Built with ❤️ by developers who've lived both sides of the open-source crisis

⭐ Star us on GitHub if you find MergeShip useful!

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
app		app
components		components
data		data
hooks		hooks
lib		lib
memory		memory
scripts		scripts
test_reports		test_reports
tests		tests
.env.example		.env.example
.gitignore		.gitignore
KNOWN_LIMITATIONS_FIXED.md		KNOWN_LIMITATIONS_FIXED.md
README.md		README.md
components.json		components.json
jsconfig.json		jsconfig.json
next.config.js		next.config.js
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
test_result.md		test_result.md
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

🚀 MergeShip - Gamified Open Source Contribution Platform

🎯 The Problem We Solve

For Maintainers 😰

For Contributors 😕

💡 The Solution

For Contributors 🎮

For Maintainers 🛡️

✨ Key Features

🎓 Learning & Progression

🤝 Community & Mentorship

🔍 Issue Explorer (Live)

🏆 Leaderboard (Real-Time)

🛠️ Maintainer Tools

🏗️ Tech Stack

Frontend

Backend

AI & APIs

Database

Deployment

🚀 Getting Started

Prerequisites

1. Clone the Repository

2. Install Dependencies

3. Environment Setup

4. Appwrite Setup

5. Run Development Server

6. Demo Mode (Testing)

📖 User Flows

Contributor Journey

Maintainer Journey

🎮 Features Breakdown

Phase 1-3: Foundation

Phase 4: Issue Explorer & Achievements

Phase 5: Maintainer Command Center

Phase 6: Community & Leaderboards

Phase 7: 4-Level Contributor System

Phase 8: UX Improvements

Phase 9: Maintainer Onboarding Wizard

Phase 10: Live Data Integration

🔐 Authentication & Security

🎨 UI/UX Design

Design System

UX Principles

📊 API Rate Limits

GitHub API

Groq AI

Appwrite

🧪 Testing

Manual Testing

Demo Mode

Test Script

📁 Project Structure

🌟 Roadmap

Current Features (v1.0)

Coming Soon (v1.1)

Future (v2.0)

💰 Business Model

Freemium Pricing

Revenue Streams

🤝 Contributing

Development Guidelines

📄 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages