diff --git a/README.md b/README.md index cab48cc..ca32948 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,226 @@ -# Collaborator +# Collaborators + +Collaborators is a GitHub bounty marketplace for open source work. Users can +create USDC bounties for public GitHub issues, submit pull request solutions, +and track solved bounties through GitHub webhook events. + +The app is built around a simple flow: + +1. Log in with GitHub through Privy. +2. Use the embedded Solana wallet associated with the account. +3. Browse or create issue bounties. +4. Submit a pull request as the solution. +5. Let the GitHub webhook verify merged work and mark the bounty as solved. + +## Features + +- **GitHub authentication**: Users sign in with GitHub through Privy. +- **Embedded Solana wallet**: Privy provides the wallet identity used for + reward attribution. +- **Bounty marketplace**: Browse active bounties, filter them, and open the + linked GitHub issue. +- **Issue search**: Find public GitHub issues and create a bounty from the dashboard. +- **Solution submissions**: Submit a pull request URL and PR number for an + active bounty. +- **Webhook tracking**: GitHub webhook events can mark bounties as solved when + linked pull requests are merged. +- **Bounty management**: Bounty owners can edit or delete active bounties. + +## Tech Stack + +- **Framework**: Next.js 15, React 19, TypeScript +- **Auth and wallet**: Privy +- **Database**: Prisma with PostgreSQL +- **GitHub API**: Octokit +- **Styling**: Tailwind CSS 4 +- **Deployment**: Vercel-ready configuration -Transform your GitHub work into on-chain rewards and reputation. Earn NFT badges and SOL tokens for your real contributions on GitHub. +## Getting Started -## 🚀 What We've Built +### Prerequisites -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. +- Node.js 20+ +- pnpm +- PostgreSQL database +- GitHub account +- Privy application -## ✨ Key Features +### Installation -- **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 +Clone the repository and install dependencies: -## 🎯 How It Works +```bash +git clone https://github.com/andr-drgm/collaborators.git +cd collaborators +pnpm install +``` -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 +Create a local environment file: -## 🛠️ Technical Stack +```bash +cp .env.example .env.local +``` -- **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 +If `.env.example` is not present in your checkout, create `.env.local` with the +variables listed below. -## 🚀 Getting Started +### Environment Variables -### Prerequisites +```env +# Database +DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE" -- Node.js 18+ and pnpm -- Solana wallet (Phantom, Solflare, etc.) -- GitHub account -- Some SOL for transaction fees +# Privy +NEXT_PUBLIC_PRIVY_APP_ID="your_privy_app_id" +PRIVY_APP_SECRET="your_privy_app_secret" -### Development Setup +# GitHub API fallback token for server-side issue lookups +GITHUB_TOKEN="your_github_token" +# or +GITHUB_ACCESS_TOKEN="your_github_access_token" -This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up: +# GitHub webhook verification +GITHUB_WEBHOOK_SECRET="your_webhook_secret" -- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit -- **Code formatting**: Ensures consistent code style across the project +# Optional public links +NEXT_PUBLIC_X_URL="https://x.com/collaborat0rs" +NEXT_PUBLIC_PRIVACY_URL="https://example.com/privacy" +NEXT_PUBLIC_TERMS_URL="https://example.com/terms" +``` -The hooks are managed by Husky and will be installed automatically when you run `pnpm install`. +Never commit real secrets. Use Vercel environment variables, a local secret +manager, or another protected deployment secret store for production values. -### Installation +### Database Setup -1. Clone the repository: +Generate the Prisma client and apply your database migrations: ```bash -git clone https://github.com/yourusername/the-collaborator.git -cd the-collaborator +pnpm prisma generate +pnpm prisma migrate dev ``` -2. Install dependencies: +For production, use your normal migration release process: ```bash -pnpm install +pnpm prisma migrate deploy ``` -3. Set up environment variables: +### Run Locally + +Start the development server: ```bash -cp .env.example .env.local +pnpm dev ``` -4. Configure your environment variables: - -```env -# GitHub OAuth -GITHUB_ID=your_github_client_id -GITHUB_SECRET=your_github_client_secret +Open [http://localhost:3000](http://localhost:3000). -# NextAuth -NEXTAUTH_SECRET=your_nextauth_secret -NEXTAUTH_URL=http://localhost:3000 +## GitHub Webhook Setup -# Solana -REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key -``` +GitHub webhooks are used to keep bounty status in sync with repository activity. -5. Run the development server: +1. Open the GitHub repository that should be tracked. +2. Go to **Settings -> Webhooks -> Add webhook**. +3. Set the payload URL to: -```bash -pnpm dev +```text +https://YOUR_DOMAIN/api/github/webhook ``` -6. Open [http://localhost:3000](http://localhost:3000) in your browser +After the URL is set: -## 🔧 Configuration +1. Set the content type to `application/json`. +2. Add the same secret used in `GITHUB_WEBHOOK_SECRET`. +3. Select issue and pull request events. +4. Save the webhook. -### GitHub OAuth Setup +The webhook handler can: -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` +- react to issue events for bounty-related issues; +- detect pull request activity; +- mark submitted bounties as solved after relevant merged PR events. -### Solana Configuration +## Bounty Workflow -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 +### For bounty creators -## 📱 User Experience Improvements +1. Log in with GitHub. +2. Search for a public GitHub issue. +3. Create a bounty with a USDC amount. +4. Install or verify the repository webhook. +5. Review submitted pull request solutions. -### For Newcomers +### For contributors -- **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. Browse active bounties on the dashboard. +2. Open the GitHub issue. +3. Implement the fix in a pull request. +4. Submit the PR URL and number through the bounty card. +5. Wait for merge and webhook verification. -### For Web3 Developers +## Available Scripts -- **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 - -### Trust & Security +```bash +pnpm dev # Start the local development server +pnpm build # Generate Prisma client and build the Next.js app +pnpm start # Start the production server +pnpm lint # Run linting +``` -- **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 repository also installs Husky hooks through the `prepare` script. -## 🎨 Design System +## Project Structure -- **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 +```text +src/app/ Next.js routes and API handlers +src/app/dashboard/ Dashboard UI +src/app/api/bounties/ Bounty and submission endpoints +src/app/api/github/ GitHub search, issue, webhook, and commit routes +src/components/ Shared UI components +src/components/dashboard Dashboard bounty and issue cards +src/lib/ Privy and webhook helpers +src/services/ GitHub service functions +prisma/schema.prisma Database schema +``` -## 🔮 Coming Soon +## Security Notes -- **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 +- Do not expose Privy secrets, GitHub tokens, database URLs, or webhook secrets + in client-side code. +- Keep `GITHUB_WEBHOOK_SECRET` enabled in production. +- Store production environment variables in the deployment platform secret store. +- Review webhook permissions before connecting repositories. +- Validate PR URLs and bounty ownership before accepting submissions. -## 🤝 Contributing +## Deployment -We welcome contributions! Please see our contributing guidelines for details on: +The project is configured for Vercel. -- Code style and standards -- Testing requirements -- Pull request process -- Community guidelines +Before deploying, configure: -## 📄 License +- `DATABASE_URL` +- `NEXT_PUBLIC_PRIVY_APP_ID` +- `PRIVY_APP_SECRET` +- `GITHUB_TOKEN` or `GITHUB_ACCESS_TOKEN` +- `GITHUB_WEBHOOK_SECRET` +- optional public URL variables -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +Then build the app: -## 🆘 Support +```bash +pnpm build +``` -- **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 +## Documentation -## 🌟 Acknowledgments +- [Privy setup guide](./PRIVY_SETUP.md) +- [Migration summary](./MIGRATION_SUMMARY.md) -- Solana Foundation for blockchain infrastructure -- GitHub for developer platform integration -- Next.js team for the amazing framework -- Our community of contributors and testers +## License ---- +Add the project license file before publishing license-specific claims. -**Collaborators** - Building the future of developer collaboration and rewards. +## Support -_Transform your contributions. Build your reputation. Get rewarded._ +Use GitHub Issues for bug reports, feature requests, and bounty discussions.