How rutvikrj26/openmuster works
Project Type and Purpose
• Full-stack decentralized web application
• Purpose: Let users connect an Ethereum wallet, authorize via GitHub OAuth, generate privacy-preserving ZK proofs over their GitHub data, and store/verify results on a Base blockchain smart contract.
File Structure
Top level directories:
– contracts & deploy-scripts / hardhat.config.js → Solidity smart contracts + deployment
– oauth-server → Express backend for GitHub OAuth, proof orchestration
– src → “old” React front-end implementation with Web3 + ZK libraries
– open-muster-next-app → Next.js/Tailwind rewrite of the UI with built-in API routes
– ignition → helper modules (e.g., ZK binding code)
– config, scripts → build/test/deploy support
README for Additional Insights
• Confirms 3 main layers: Frontend (React/Next.js), Backend (Express OAuth), Smart Contracts (Solidity + ZKProof verification via zkVerify)
• External integrations: GitHub API, MetaMask/Ethereum node, zkVerify API
Main Components & Their Relationships
a. Frontend (Browser)
– UI layer in React (src/) or Next.js (open-muster-next-app/)
– Invokes Web3 wallets (MetaMask) for signature and transaction submission
– Pulls public GitHub data via GitHub REST API client libraries
– Triggers local ZK proof generation modules (RiscZero, Noir, Groth16, FFlonk)
– Calls Next.js API routes or directly calls the OAuth server for token exchange
b. OAuth Server (Express in oauth-server/)
– Hosts endpoints to handle GitHub OAuth callbacks
– Verifies signed wallet messages & GitHub tokens
– Optionally generates/forwards ZK proofs if offloaded from client
– Writes verification results to Smart Contract via ethers.js
c. Blockchain Layer
– Base Sepolia chain running your GitHubProfileScoreZK.sol & ZKVerifyBridge.sol
– Hardhat scripts (deploy-scripts/) handle compilation & deployment
– Users’ signature + GitHub verification stored on-chain
d. ZKVerify Service (External)
– Receives proof submissions (RiscZero, Noir, Groth16, FFlonk)
– Responds with verification receipts
– Bridge contract writes final proof results on-chain
e. GitHub API (External)
– Provides public & private repo metadata once the user has OAuth’d
Architectural Patterns & Design Principles
• Monorepo microservices: separate folders for frontends, backend, contracts
• API layering: Next.js API routes vs. standalone Express OAuth server
• On-chain/off-chain separation: heavy computation (ZK proof gen) off-chain; state (verification status & scores) on-chain
• Dependency injection/config override (config-overrides.js, config/*.js)
– Place “User Browser” (with MetaMask) on the far left
• React App (src/)
• Next.js App (open-muster-next-app/)
• GitHub API (OAuth flow)
• Ethereum Node Provider (Infura/Alchemy)
• ZK proof modules
• In ← OAuth redirect from GitHub
• Out → Smart Contracts
– Connect ZK proof modules (inside UI or OAuth server) to zkVerify API and then to Smart Contracts
Diagramming Conventions
– Use rounded rectangles for services (UI, OAuth server)
– Use clouds for external APIs (GitHub, zkVerify, Infura)
• Blue = UI
• Green = Backend / Auth
• Orange = Blockchain
• Gray = External
Final Checklist
[ ] All four ZK proof systems and their flows are represented
[ ] OAuth handshake with GitHub is clear
[ ] Wallet signature & contract write path is shown
[ ] Next.js API routes vs. Express routes are distinguished