andr-drgm · Choonsiks · Jun 8, 2026
diff --git a/README.md b/README.md
@@ -1,180 +1,206 @@
-# Collaborator
+# Collaborators
 
-Transform your GitHub work into on-chain rewards and reputation. Earn NFT badges and SOL tokens for your real contributions on GitHub.
+Collaborators is a GitHub bounty marketplace that connects open-source work to on-chain rewards and reputation. Sponsors can attach USDC-denominated bounties to GitHub issues, contributors can submit pull requests as solutions, and the app tracks bounty status from issue discovery through PR submission and verification.
 
-## 🚀 What We've Built
+## What you can do
 
-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.
+- Browse active bounties across public GitHub repositories.
+- Search GitHub issues and create a bounty for an issue you want solved.
+- Submit a pull request URL as your solution to an active bounty.
+- Track your posted bounties, submitted solutions, and solved bounties from one dashboard.
+- Link GitHub identity and a wallet through Privy so accepted work can be associated with the right contributor.
+- Install or track the GitHub bot/webhook flow needed to verify repository activity.
 
-## ✨ Key Features
+## How the bounty flow works
 
-- **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
+### For sponsors
 
-## 🎯 How It Works
+1. Sign in with Privy and link GitHub.
+2. Search for a GitHub issue or select one of your own issues.
+3. Create a bounty with an amount, title, description, issue URL, and repository metadata.
+4. The bounty appears in the active bounty feed with `bounty` and `usdc-reward` metadata.
+5. Review submitted pull requests.
+6. When a winning PR is merged, the webhook flow marks the submission approved and the bounty solved.
 
-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
+### For contributors
 
-## 🛠️ Technical Stack
+1. Sign in with Privy and link GitHub.
+2. Link or use the wallet created by Privy.
+3. Pick an active bounty from the dashboard.
+4. Open a pull request that solves the linked GitHub issue.
+5. Submit the PR URL through the bounty card.
+6. If the PR is merged and the bounty is still active, the app verifies the submission and records the solver.
 
-- **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
-
-## 🚀 Getting Started
-
-### Prerequisites
+## Current product areas
 
-- Node.js 18+ and pnpm
-- Solana wallet (Phantom, Solflare, etc.)
-- GitHub account
-- Some SOL for transaction fees
+The dashboard is the main application surface and is organized around these views:
 
-### Development Setup
+- **Active Bounties**: Browse open bounty opportunities and submit PR solutions.
+- **My Issues**: Load GitHub issues for the authenticated user.
+- **Solved Issues**: Review bounties solved by the current user.
+- **My Bounties**: Manage bounties created by the current user.
 
-This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up:
+The legacy contribution-tracking and NFT badge components are archived under `src/components/dashboard/archive`, `src/hooks/archive`, and `src/utils/archive` so they can be recovered later without confusing the current bounty marketplace MVP.
 
-- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit
-- **Code formatting**: Ensures consistent code style across the project
+## Tech stack
 
-The hooks are managed by Husky and will be installed automatically when you run `pnpm install`.
+- **Framework**: Next.js 15, React 19, TypeScript
+- **Auth and wallet**: Privy with GitHub OAuth and Solana wallet support
+- **Database**: Prisma with PostgreSQL
+- **GitHub integration**: Octokit, GitHub search APIs, issue metadata, pull request webhook handling
+- **Styling**: Tailwind CSS 4 with custom UI components
+- **Deployment target**: Vercel or any Node-compatible host that supports Next.js and PostgreSQL
+
+## Repository structure
+
+```text
+src/app/page.tsx                         Landing page
+src/app/dashboard/page.tsx               Main bounty dashboard
+src/app/api/bounties/route.ts            List and create bounties
+src/app/api/bounties/[id]/route.ts       Update/delete individual bounties
+src/app/api/bounties/submissions/route.ts Submit and list PR solutions
+src/app/api/bounties/solved/route.ts     Solved bounty lookups
+src/app/api/github/*                     GitHub issue, search, webhook, and bot endpoints
+src/components/dashboard/BountyCard.tsx  Bounty display and PR submission UI
+src/components/dashboard/IssueCard.tsx   GitHub issue display and bounty creation UI
+src/components/dashboard/WalletConnect.tsx Wallet status UI
+src/lib/privy.ts                         Privy token verification and user sync
+src/lib/github-webhook.ts                GitHub webhook signature verification
+prisma/schema.prisma                     User, bounty, submission, and bot models
+```
 
-### Installation
+## Local development
 
-1. Clone the repository:
+### Prerequisites
 
-```bash
-git clone https://github.com/yourusername/the-collaborator.git
-cd the-collaborator
-```
+- Node.js 18 or newer
+- pnpm
+- PostgreSQL database
+- Privy app with GitHub OAuth enabled
+- GitHub personal access token or OAuth token for repository and issue lookups
 
-2. Install dependencies:
+### Install dependencies
 
 ```bash
 pnpm install
 ```
 
-3. Set up environment variables:
+`postinstall` runs `prisma generate`, and `prepare` installs Husky hooks.
 
-```bash
-cp .env.example .env.local
-```
+### Configure environment variables
 
-4. Configure your environment variables:
+Create `.env.local` and set the values used by the app:
 
 ```env
-# GitHub OAuth
-GITHUB_ID=your_github_client_id
-GITHUB_SECRET=your_github_client_secret
+# Database
+DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE"
+
+# Privy
+NEXT_PUBLIC_PRIVY_APP_ID="your-privy-app-id"
+PRIVY_APP_SECRET="your-privy-app-secret"
+
+# GitHub API fallback tokens
+GITHUB_TOKEN="github_pat_or_classic_pat"
+GITHUB_ACCESS_TOKEN="optional_alternate_github_token"
+GITHUB_WEBHOOK_SECRET="optional_webhook_secret"
+
+# Public links used by the landing page
+NEXT_PUBLIC_X_URL="https://x.com/collaborat0rs"
+NEXT_PUBLIC_PRIVACY_URL="https://example.com/privacy"
+NEXT_PUBLIC_TERMS_URL="https://example.com/terms"
+```
+
+Privy setup notes live in [`PRIVY_SETUP.md`](./PRIVY_SETUP.md). In the Privy dashboard, enable GitHub OAuth and turn on **Return OAuth tokens** so GitHub API calls can use the authenticated user's GitHub access token.
 
-# NextAuth
-NEXTAUTH_SECRET=your_nextauth_secret
-NEXTAUTH_URL=http://localhost:3000
+### Prepare the database
 
-# Solana
-REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key
+```bash
+pnpm prisma generate
+pnpm prisma migrate dev
 ```
 
-5. Run the development server:
+### Run the app
 
 ```bash
 pnpm dev
 ```
 
-6. Open [http://localhost:3000](http://localhost:3000) in your browser
-
-## 🔧 Configuration
-
-### GitHub OAuth Setup
+Open <http://localhost:3000> and sign in through the Privy modal.
 
-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`
+## GitHub webhook setup
 
-### Solana Configuration
+The webhook endpoint is:
 
-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
-
-## 📱 User Experience Improvements
-
-### For Newcomers
-
-- **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
+```text
+POST /api/github/webhook
+```
 
-### For Web3 Developers
+Configure your GitHub app or repository webhook to send at least these events:
 
-- **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
+- `ping`
+- `issues`
+- `pull_request`
 
-### Trust & Security
+If `GITHUB_WEBHOOK_SECRET` is set, the app verifies `x-hub-signature-256` before processing events. In development the route logs signature mismatches instead of hard-failing so local testing is easier.
 
-- **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
+## Important data models
 
-## 🎨 Design System
+- `User`: Privy identity, GitHub username, wallet address, and relationships.
+- `Bounty`: GitHub issue metadata, amount, status, poster, labels, and solved state.
+- `BountySubmission`: contributor PR URL, PR number, status, and verification state.
+- `BotInstallation`: repository-level bot installation tracking.
 
-- **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
+## API overview
 
-## 🔮 Coming Soon
+### Public
 
-- **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
+- `GET /api/bounties?status=ACTIVE&limit=50` — list bounties by status.
 
-## 🤝 Contributing
+### Authenticated with `Authorization: Bearer <privy-token>`
 
-We welcome contributions! Please see our contributing guidelines for details on:
+- `POST /api/bounties` — create a bounty for a GitHub issue.
+- `GET /api/bounties/my` — list bounties created by the current user.
+- `PATCH /api/bounties/[id]` — update a bounty amount/status.
+- `DELETE /api/bounties/[id]` — cancel/delete a bounty.
+- `POST /api/bounties/submissions` — submit a PR URL for a bounty.
+- `GET /api/bounties/submissions` — list the current user's submissions or a bounty's submissions.
+- `GET /api/bounties/solved` — list solved bounties for the current user.
+- `GET /api/github/user/issues` — fetch issues for the authenticated GitHub user.
 
-- Code style and standards
-- Testing requirements
-- Pull request process
-- Community guidelines
+## Security and operations notes
 
-## 📄 License
+- Keep `PRIVY_APP_SECRET`, `DATABASE_URL`, GitHub tokens, and webhook secrets server-side only.
+- Never expose GitHub access tokens to the client; use Privy access tokens for app authentication.
+- Use GitHub webhook signatures in production.
+- Store wallet addresses, not private keys.
+- Confirm payout and settlement logic before handling high-value bounties.
+- The archived token-claiming code references legacy mint-authority environment variables and should not be re-enabled without a fresh security review.
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+## Roadmap ideas
 
-## 🆘 Support
+- Fully automated GitHub label creation when a bounty is posted.
+- On-chain escrow and settlement integration for funded bounties.
+- Better submission ranking and review workflow for maintainers.
+- Contributor reputation pages and public solved-bounty history.
+- Notifications for PR submission, approval, rejection, and payout events.
+- Public API access for external bounty aggregators and agent workflows.
 
-- **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
+## Contributing
 
-## 🌟 Acknowledgments
+1. Fork the repository.
+2. Create a focused branch.
+3. Keep changes small and tied to a single issue.
+4. Run the relevant checks before opening a PR.
+5. Reference the issue in your PR description.
 
-- Solana Foundation for blockchain infrastructure
-- GitHub for developer platform integration
-- Next.js team for the amazing framework
-- Our community of contributors and testers
+Example:
 
----
+```text
+Closes #40
+```
 
-**Collaborators** - Building the future of developer collaboration and rewards.
+## Support
 
-_Transform your contributions. Build your reputation. Get rewarded._
+- Use GitHub Issues for bugs and feature requests.
+- Review [`PRIVY_SETUP.md`](./PRIVY_SETUP.md) for authentication and wallet setup details.
+- Check `MIGRATION_SUMMARY.md` for context on the dashboard migration from the legacy contribution tracker to the current bounty marketplace MVP.