andr-drgm · nicovaleops · May 13, 2026
diff --git a/README.md b/README.md
@@ -1,61 +1,103 @@
-# 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 for open-source work. Project owners attach USDC rewards to public GitHub issues, contributors submit pull requests, and rewards are released when the linked PR is merged and verified.
 
-## 🚀 What We've Built
+The app combines GitHub issue discovery, Privy authentication, Solana wallet support, and bounty/submission tracking in a Next.js dashboard.
 
-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.
+## What you can do
 
-## ✨ Key Features
+### For contributors
 
-- **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
+- Browse open GitHub issues with active USDC rewards.
+- Connect with GitHub through Privy authentication.
+- Link a Solana wallet for reward payouts.
+- Submit a pull request URL as proof of work.
+- Track pending, verified, and solved bounty submissions.
 
-## 🎯 How It Works
+### For bounty posters
 
-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
+- Add funded rewards to public GitHub issues.
+- Monitor submitted PRs from contributors.
+- Use GitHub bot installation status to support verification flows.
+- Keep bounty status and solver history in one dashboard.
 
-## 🛠️ Technical Stack
+## How it works
 
-- **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
+```mermaid
+flowchart LR
+    A[Poster selects a GitHub issue] --> B[Poster creates a USDC bounty]
+    B --> C[Contributor finds the bounty]
+    C --> D[Contributor opens a pull request]
+    D --> E[Contributor submits the PR URL]
+    E --> F[Bot / reviewer verifies merge]
+    F --> G[Reward is released to contributor wallet]
+```
 
-## 🚀 Getting Started
+1. **Authenticate** — users sign in with GitHub through Privy.
+2. **Discover or create bounties** — the dashboard lists bounty-backed GitHub issues and user-owned issues.
+3. **Build the fix** — contributors work directly in GitHub using the normal fork/branch/PR workflow.
+4. **Submit proof** — contributors paste the merged or review-ready PR URL into Collaborators.
+5. **Verify and pay** — the platform tracks PR status and releases the bounty when the solution is accepted.
+
+## Tech stack
+
+| Area | Technology |
+| --- | --- |
+| Framework | Next.js 15, React 19, TypeScript |
+| Auth | Privy with GitHub login |
+| Wallets | Privy embedded Solana wallets + external wallet support |
+| Database | Prisma + PostgreSQL |
+| GitHub integration | Octokit / GitHub APIs |
+| Styling | Tailwind CSS |
+| Deployment | Vercel-ready |
+
+## Repository structure
+
+```text
+.
+├── prisma/                 # Prisma schema and database models
+├── public/                 # Static assets and app icons
+├── src/app/                # Next.js app routes and API handlers
+├── src/components/         # Reusable UI and dashboard components
+├── src/hooks/              # Privy/auth helper hooks
+├── src/services/           # GitHub and app service helpers
+├── src/utils/              # Shared constants and utility functions
+└── package.json            # Scripts and dependencies
+```
 
-### Prerequisites
+## Prerequisites
 
-- Node.js 18+ and pnpm
-- Solana wallet (Phantom, Solflare, etc.)
-- GitHub account
-- Some SOL for transaction fees
+- Node.js 18+
+- pnpm
+- PostgreSQL database
+- Privy app ID / credentials
+- GitHub OAuth app credentials
+- Solana wallet configuration for payouts
 
-### Development Setup
+## Environment variables
 
-This project uses Git hooks to ensure code quality. When you clone the repository, the following will be automatically set up:
+Create `.env.local` from your local secret store or deployment environment.
 
-- **Pre-commit hooks**: Automatically runs `pnpm lint` before each commit
-- **Code formatting**: Ensures consistent code style across the project
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `NEXT_PUBLIC_PRIVY_APP_ID` | Yes | Privy client app ID used by the frontend provider. |
+| `PRIVY_APP_SECRET` | Yes | Server-side Privy verification secret, if used by API routes. |
+| `DATABASE_URL` | Yes | PostgreSQL connection string for Prisma. |
+| `GITHUB_ID` | Yes | GitHub OAuth app client ID. |
+| `GITHUB_SECRET` | Yes | GitHub OAuth app client secret. |
+| `NEXTAUTH_SECRET` | If using NextAuth routes | Secret for auth session signing. |
+| `NEXTAUTH_URL` | If using NextAuth routes | Local or deployed application URL. |
+| `REACT_APP_MINT_AUTHORITY_SECRET_KEY` | If minting/reward flows require it | Solana mint authority key for token operations. |
 
-The hooks are managed by Husky and will be installed automatically when you run `pnpm install`.
+> Never commit `.env.local`, private keys, OAuth secrets, or wallet seed material.
 
-### Installation
+## Local development
 
 1. Clone the repository:
 
 ```bash
-git clone https://github.com/yourusername/the-collaborator.git
-cd the-collaborator
+git clone https://github.com/andr-drgm/collaborators.git
+cd collaborators
 ```
 
 2. Install dependencies:
@@ -64,117 +106,151 @@ cd the-collaborator
 pnpm install
 ```
 
-3. Set up environment variables:
+3. Configure environment variables:
 
 ```bash
-cp .env.example .env.local
+touch .env.local
+# then fill in the required values from the table above
 ```
 
-4. Configure your environment variables:
+4. Generate Prisma client:
 
-```env
-# GitHub OAuth
-GITHUB_ID=your_github_client_id
-GITHUB_SECRET=your_github_client_secret
+```bash
+pnpm prisma generate
+```
 
-# NextAuth
-NEXTAUTH_SECRET=your_nextauth_secret
-NEXTAUTH_URL=http://localhost:3000
+5. Run database migrations or sync your schema, depending on your environment:
 
-# Solana
-REACT_APP_MINT_AUTHORITY_SECRET_KEY=your_mint_authority_key
+```bash
+pnpm prisma migrate dev
+# or: pnpm prisma db push
 ```
 
-5. Run the development server:
+6. Start the development server:
 
 ```bash
 pnpm dev
 ```
 
-6. Open [http://localhost:3000](http://localhost:3000) in your browser
+7. Open [http://localhost:3000](http://localhost:3000).
+
+## Useful scripts
+
+| Command | Description |
+| --- | --- |
+| `pnpm dev` | Start the local Next.js development server. |
+| `pnpm build` | Generate Prisma client and create a production build. |
+| `pnpm start` | Start the production server after building. |
+| `pnpm lint` | Run the configured lint command. |
+| `pnpm postinstall` | Generate Prisma client after install. |
+| `pnpm prepare` | Install Husky git hooks. |
+
+## GitHub OAuth setup
+
+1. Open GitHub Developer Settings.
+2. Create a new OAuth App.
+3. For local development, set the callback URL to:
+
+```text
+http://localhost:3000/api/auth/callback/github
+```
+
+4. For production, set the callback URL to your deployed domain.
+5. Copy the client ID and client secret into your environment variables.
+
+## Privy setup
 
-## 🔧 Configuration
+1. Create a Privy app.
+2. Enable GitHub as a login method.
+3. Configure Solana embedded wallets if you want wallet creation on login.
+4. Add your local and production domains to the allowed app URLs.
+5. Set `NEXT_PUBLIC_PRIVY_APP_ID` and any server-side Privy secrets in your environment.
 
-### GitHub OAuth Setup
+## Solana configuration
 
-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`
+The app is configured for Solana wallet support through Privy. Review `src/app/PrivyProviders.tsx` before changing network behavior.
 
-### Solana Configuration
+Current provider defaults include:
 
-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
+- Solana Mainnet
+- Solana Devnet
+- Devnet as the default chain for development flows
 
-## 📱 User Experience Improvements
+Use devnet while testing wallet and payout flows. Switch to mainnet only after confirming reward funding, verification, and payout behavior end to end.
 
-### For Newcomers
+## Contributor workflow
 
-- **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. Pick an active bounty from the dashboard.
+2. Open the linked GitHub issue.
+3. Fork the target repository and create a focused branch.
+4. Implement the fix with tests or documentation updates where appropriate.
+5. Open a pull request that references the issue.
+6. Submit the PR URL in Collaborators.
+7. Track the submission status from the dashboard.
 
-### For Web3 Developers
+## Bounty poster workflow
 
-- **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. Sign in with GitHub.
+2. Choose one of your public GitHub issues.
+3. Create a bounty with the reward amount and description.
+4. Install or verify the GitHub bot where required.
+5. Review submitted pull requests.
+6. Accept the solution and complete reward release once the PR is merged.
 
-### Trust & Security
+## Deployment checklist
 
-- **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
+Before deploying to production:
 
-## 🎨 Design System
+- [ ] Production database is provisioned and migrated.
+- [ ] Privy production app URL is configured.
+- [ ] GitHub OAuth production callback URL is configured.
+- [ ] Solana network and wallet settings are reviewed.
+- [ ] Secret variables are set in the hosting provider.
+- [ ] `pnpm build` passes.
+- [ ] Bounty creation, PR submission, verification, and payout flows are tested on devnet or a staging environment.
 
-- **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
+## Troubleshooting
 
-## 🔮 Coming Soon
+### GitHub login fails
 
-- **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
+- Check `GITHUB_ID` and `GITHUB_SECRET`.
+- Confirm the callback URL exactly matches the app URL.
+- Verify the GitHub OAuth app is not restricted to the wrong domain.
 
-## 🤝 Contributing
+### Wallet is not created or connected
 
-We welcome contributions! Please see our contributing guidelines for details on:
+- Confirm the Privy app ID is correct.
+- Check that Solana embedded wallets are enabled in Privy.
+- Reload the session after changing Privy settings.
 
-- Code style and standards
-- Testing requirements
-- Pull request process
-- Community guidelines
+### Prisma client errors
 
-## 📄 License
+- Run `pnpm prisma generate`.
+- Confirm `DATABASE_URL` is set.
+- Apply migrations or run `pnpm prisma db push` for local development.
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### Build fails after dependency changes
 
-## 🆘 Support
+- Delete `node_modules` and reinstall with `pnpm install`.
+- Confirm your Node.js version is 18 or newer.
+- Re-run `pnpm prisma generate` before building.
 
-- **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
+## Security notes
 
-## 🌟 Acknowledgments
+- Do not commit OAuth secrets, wallet private keys, or database credentials.
+- Use devnet for payout testing until the full reward flow is verified.
+- Keep reward-release logic server-side and validate all submitted PR URLs.
+- Treat GitHub webhook payloads and client-submitted PR URLs as untrusted input.
+- Log verification decisions enough to debug payouts without exposing secrets.
 
-- Solana Foundation for blockchain infrastructure
-- GitHub for developer platform integration
-- Next.js team for the amazing framework
-- Our community of contributors and testers
+## Roadmap ideas
 
----
+- Automated PR merge verification through GitHub webhooks.
+- Richer bounty filters by language, reward size, and repository.
+- Contributor reputation pages.
+- Bounty escrow status and payout history.
+- Team and organization dashboards.
 
-**Collaborators** - Building the future of developer collaboration and rewards.
+## License
 
-_Transform your contributions. Build your reputation. Get rewarded._
+This project is licensed under the MIT License. See the repository license file for details.