Skip to content

docs: refresh README for current bounty workflow #53

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qingfeng312 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: refresh README for current bounty workflow #53

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 113 additions & 133 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,180 +1,160 @@
# Collaborator

Transform your GitHub work into on-chain rewards and reputation. Earn NFT badges and SOL tokens for your real contributions on GitHub.

## 🚀 What We've Built

Collaborators is a Web3 platform that automatically converts your GitHub activity into verifiable on-chain achievements. Every meaningful contribution mints NFT badges and earns SOL tokens, helping you build your on-chain reputation while getting rewarded for open-source collaboration.

## ✨ Key Features

- **GitHub Integration**: Seamlessly connect your GitHub account to track contributions
- **Automatic Rewards**: Earn SOL tokens for commits, pull requests, reviews, and issue resolution
- **NFT Badges**: Unique digital credentials minted for your achievements
- **On-Chain Reputation**: Verifiable proof of your contributions stored on Solana blockchain
- **Real-Time Tracking**: Monitor your contribution activity with GitHub-style heatmaps
- **Secure Wallet Integration**: Support for Phantom, Solflare, and other Solana wallets

## 🎯 How It Works
# Collaborators

Collaborators is a GitHub-first bounty marketplace for open-source work. Maintainers publish USDC-denominated rewards on GitHub issues, contributors submit pull requests, and the app tracks bounty status, submissions, verification, and solver history.

The application is built as a Next.js dashboard with Privy authentication, Prisma/PostgreSQL persistence, GitHub issue and webhook integrations, and Solana wallet support for the reward flow.

## What The App Does

- Turns GitHub issues into bounty listings with repository, issue, label, amount, poster, and status metadata.
- Lets contributors discover active bounties, open the source issue, and submit a PR URL for review.
- Tracks each bounty submission as `PENDING`, `APPROVED`, or `REJECTED`.
- Marks bounties as solved when a maintainer closes the tracked issue or a webhook records the accepted solver.
- Stores user profile, GitHub identity, Privy wallet identity, bot installation, and legacy project-assignment data.
- Provides a dashboard for posted bounties, submitted solutions, issue search, profile state, and wallet connection.

## Tech Stack

- Next.js 15 and React 19
- TypeScript
- Tailwind CSS 4
- Prisma 6 with PostgreSQL
- Privy for embedded authentication and wallet identity
- Octokit for GitHub API access
- Solana Web3.js and SPL Token helpers
- Vercel-oriented deployment config

## Repository Map

```text
src/app/ Next.js app routes and API handlers
src/app/api/bounties/ Bounty listing, detail, and submission APIs
src/app/api/github/ GitHub issue search, labels, webhook, and bot installation APIs
src/components/dashboard/ Dashboard cards and bounty UI
src/hooks/usePrivyAuth.ts Privy session helper
src/lib/privy.ts Server-side Privy client
src/prisma.ts Prisma client export
prisma/schema.prisma Database schema
PRIVY_SETUP.md Privy setup notes
MIGRATION_SUMMARY.md Migration context from legacy project flows
```

1. **Connect GitHub**: Log in with your GitHub account
2. **Link Wallet**: Connect your Solana wallet (Phantom, Solflare, etc.)
3. **Start Contributing**: Continue your normal GitHub workflow
4. **Get Rewarded**: Earn tokens and NFT badges automatically
## Data Model

## 🛠️ Technical Stack
The current Prisma schema centers on these records:

- **Frontend**: Next.js 14, React, TypeScript
- **Styling**: Tailwind CSS with custom design system
- **Blockchain**: Solana blockchain integration
- **Authentication**: NextAuth.js with GitHub OAuth
- **Database**: Prisma with PostgreSQL
- **Deployment**: Vercel-ready configuration
- `User`: profile, GitHub login, Privy id, wallet address, unclaimed token count, and relationships.
- `Bounty`: one reward listing per GitHub issue and repository, with USDC amount, labels, poster, status, solved fields, and submissions.
- `BountySubmission`: a contributor PR URL, PR number, status, verification fields, and the submitting user.
- `BotInstallation`: installed GitHub bot state for a repository.
- `Project` and `ProjectAssignment`: legacy project-tracking models kept for migration compatibility.

## 🚀 Getting Started
## Local Setup

### Prerequisites

- Node.js 18+ and pnpm
- Solana wallet (Phantom, Solflare, etc.)
- GitHub account
- Some SOL for transaction fees
- Node.js 20 or newer
- pnpm
- PostgreSQL
- A Privy app
- GitHub OAuth or GitHub app credentials, depending on the flow you are testing

### Development Setup
### Install

This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up:
```bash
git clone https://github.com/andr-drgm/collaborators.git
cd collaborators
pnpm install
```

### Environment

- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit
- **Code formatting**: Ensures consistent code style across the project
Create `.env.local` and configure the values used by the app:

The hooks are managed by Husky and will be installed automatically when you run `pnpm install`.
```env
DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DATABASE

### Installation
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
PRIVY_APP_SECRET=your_privy_app_secret

1. Clone the repository:
GITHUB_WEBHOOK_SECRET=your_webhook_secret

```bash
git clone https://github.com/yourusername/the-collaborator.git
cd the-collaborator
NEXT_PUBLIC_X_URL=https://x.com/collaborat0rs
NEXT_PUBLIC_PRIVACY_URL=https://example.com/privacy
NEXT_PUBLIC_TERMS_URL=https://example.com/terms
```

2. Install dependencies:
Use local-only test credentials for development. Do not commit real secrets.

```bash
pnpm install
```
### Database

3. Set up environment variables:
Generate the Prisma client after dependency installation:

```bash
cp .env.example .env.local
pnpm prisma generate
```

4. Configure your environment variables:
Apply migrations or sync the schema with the workflow used by your deployment:

```env
# GitHub OAuth
GITHUB_ID=your_github_client_id
GITHUB_SECRET=your_github_client_secret

# NextAuth
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000

# Solana
REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key
```bash
pnpm prisma migrate dev
```

5. Run the development server:
### Run

```bash
pnpm dev
```

6. Open [http://localhost:3000](http://localhost:3000) in your browser

## 🔧 Configuration

### GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set the callback URL to `http://localhost:3000/api/auth/callback/github`
4. Copy the Client ID and Client Secret to your `.env.local`

### Solana Configuration

1. Set up a Solana wallet with some SOL
2. Configure your mint authority for token distribution
3. Update the mint address in the dashboard component
Open `http://localhost:3000`.

## 📱 User Experience Improvements
## Common Workflows

### For Newcomers
### Post Or Track A Bounty

- **Clear Value Proposition**: "Transform GitHub work into on-chain rewards and reputation"
- **Key Terms Explained**: Hover tooltips for SOL tokens, NFT badges, and on-chain reputation
- **Simple Steps**: 3-step onboarding process clearly explained
- **Visual Flowchart**: Step-by-step process visualization
1. Create a GitHub issue for the work.
2. Add bounty metadata in the Collaborators dashboard.
3. The app stores the issue id, repository owner/name, title, description, labels, poster, and USDC amount.
4. Contributors use the linked issue and repository to prepare their PR.

### For Web3 Developers
### Submit A Solution

- **Advanced Features**: Detailed contribution tracking and analytics
- **Technical Details**: Comprehensive dashboard with GitHub-style heatmaps
- **Wallet Integration**: Seamless Solana wallet connection
- **Real-Time Updates**: Live contribution tracking and reward calculation
1. Open an active bounty.
2. Create a PR in the target repository.
3. Submit the PR URL through the bounty submission flow.
4. The app records the PR number and keeps the submission pending until verification.

### Trust & Security
### Webhook Verification

- **Security Information**: Clear explanations of data privacy and wallet security
- **FAQ Section**: Common questions about tracking, rewards, and supported wallets
- **Help Tooltips**: Contextual assistance throughout the platform
- **Onboarding Guidance**: Step-by-step help for wallet setup
The GitHub webhook route listens for issue and PR events. When a tracked issue is closed or a completion signal is detected, the app can update the matching bounty as solved and record solver metadata.

## 🎨 Design System
Configure the webhook secret with `GITHUB_WEBHOOK_SECRET` and point GitHub to the deployed webhook route.

- **Color Palette**: Cyan to teal gradients with dark theme
- **Typography**: Geist Sans and Geist Mono fonts
- **Components**: Consistent card designs with hover effects
- **Responsive**: Mobile-first design with desktop optimizations
- **Accessibility**: High contrast ratios and keyboard navigation
## Scripts

## 🔮 Coming Soon

- **Team Leaderboards**: Compete with your team and climb the ranks
- **Exclusive NFT Tiers**: Rare collectibles for top contributors
- **API Access**: Integrate rewards into your own applications
- **Multi-Chain Support**: Expand beyond Solana to other blockchains

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details on:

- Code style and standards
- Testing requirements
- Pull request process
- Community guidelines

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```bash
pnpm dev # Start local development server
pnpm build # Generate Prisma client and build Next.js
pnpm start # Start production build
pnpm lint # Run lint command configured by the project
```

## 🆘 Support
`postinstall` runs `prisma generate`, and Husky is prepared through the `prepare` script.

- **Documentation**: Check this README and inline help tooltips
- **Issues**: Report bugs or feature requests via GitHub Issues
- **Discussions**: Join community discussions for help and ideas
- **Email**: Contact the team directly for urgent matters
## Deployment Notes

## 🌟 Acknowledgments
- Set the same environment variables in Vercel or your hosting provider.
- Ensure the production database is reachable by Prisma.
- Keep webhook secrets and Privy secrets server-side only.
- Run the production build before release to catch Prisma and Next.js integration issues.

- Solana Foundation for blockchain infrastructure
- GitHub for developer platform integration
- Next.js team for the amazing framework
- Our community of contributors and testers
## Security Notes

---
- Never expose `PRIVY_APP_SECRET`, `DATABASE_URL`, private wallet keys, or webhook secrets in client-side code.
- Validate PR URLs before accepting bounty submissions.
- Treat webhook events as untrusted until signature verification succeeds.
- Keep payout state separate from display state so pending submissions cannot be mistaken for approved rewards.

**Collaborators** - Building the future of developer collaboration and rewards.
## Contributing

_Transform your contributions. Build your reputation. Get rewarded._
Contributions are welcome. For bounty work, link your PR to the relevant GitHub issue and keep changes scoped to the requested behavior. For documentation changes, prefer repository-accurate setup steps over broad marketing copy.