# rutvikrj26/openmuster architecture

> Architecture diagram of the GitHub repository rutvikrj26/openmuster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rutvikrj26/openmuster
- Repository: https://github.com/rutvikrj26/openmuster

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User Browser<br/>(MetaMask)"]:::external

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        ReactApp["React App"]:::frontend
        NextApp["Next.js App"]:::frontend
        ZKModules["ZK Proof Modules<br/>(RiscZero, Noir, Groth16, FFlonk)"]:::frontend
    end

    %% Auth Layer
    OAuth["OAuth Server"]:::backend

    %% Blockchain Layer
    SmartContracts["Smart Contracts on Base Sepolia"]:::blockchain

    %% External Services
    GitHubAPI["GitHub API"]:::external
    EthereumRPC["Ethereum RPC<br/>(Infura/Alchemy)"]:::external
    zkVerifyAPI["zkVerify API"]:::external

    %% Flows
    User -->|"opens UI"| ReactApp
    User -->|"opens UI"| NextApp

    ReactApp -->|"OAuth code/GitHub data"| GitHubAPI
    NextApp -->|"OAuth code → server"| OAuth

    ReactApp -->|"eth_requestAccounts/sign txn"| EthereumRPC
    NextApp -->|"eth_requestAccounts/sign txn"| EthereumRPC

    ReactApp -->|"trigger proof"| ZKModules
    NextApp -->|"trigger proof"| ZKModules

    ZKModules -->|"Proof JSON"| zkVerifyAPI
    zkVerifyAPI -->|"verification receipt"| SmartContracts

    OAuth -->|"token exchange → GitHub"| GitHubAPI
    OAuth -->|"verify wallet msg"| EthereumRPC
    OAuth -->|"write result via ethers.js"| SmartContracts

    ReactApp -->|"call API routes"| NextApp
    NextApp -->|"calls OAuth endpoints"| OAuth

    %% Click events for component mapping
    click ReactApp "https://github.com/rutvikrj26/openmuster/tree/main/src/"
    click ReactApp "https://github.com/rutvikrj26/openmuster/blob/main/src/App.js"
    click ReactApp "https://github.com/rutvikrj26/openmuster/blob/main/src/index.js"
    click ReactApp "https://github.com/rutvikrj26/openmuster/tree/main/src/components/"
    click ReactApp "https://github.com/rutvikrj26/openmuster/tree/main/src/services/"
    click NextApp "https://github.com/rutvikrj26/openmuster/tree/main/open-muster-next-app/"
    click NextApp "https://github.com/rutvikrj26/openmuster/tree/main/open-muster-next-app/app/"
    click NextApp "https://github.com/rutvikrj26/openmuster/tree/main/open-muster-next-app/app/api/"
    click NextApp "https://github.com/rutvikrj26/openmuster/tree/main/open-muster-next-app/components/"
    click NextApp "https://github.com/rutvikrj26/openmuster/tree/main/open-muster-next-app/hooks/"
    click NextApp "https://github.com/rutvikrj26/openmuster/tree/main/open-muster-next-app/lib/"
    click NextApp "https://github.com/rutvikrj26/openmuster/blob/main/open-muster-next-app/next.config.mjs"
    click NextApp "https://github.com/rutvikrj26/openmuster/blob/main/open-muster-next-app/tailwind.config.js"
    click OAuth "https://github.com/rutvikrj26/openmuster/blob/main/oauth-server/server.js"
    click OAuth "https://github.com/rutvikrj26/openmuster/blob/main/oauth-server/.env.example"
    click OAuth "https://github.com/rutvikrj26/openmuster/blob/main/oauth-server/contractABI.json"
    click OAuth "https://github.com/rutvikrj26/openmuster/blob/main/oauth-server/bountyContractABI.json"
    click OAuth "https://github.com/rutvikrj26/openmuster/blob/main/oauth-server/package.json"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/tree/main/contracts/"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/blob/main/contracts/*.sol"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/blob/main/hardhat.config.js"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/tree/main/deploy-scripts/"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/blob/main/deploy-scripts/deploy.js"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/blob/main/deploy-scripts/deploy-bounty.js"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/blob/main/deploy-scripts/deploy-zk-contracts.js"
    click SmartContracts "https://github.com/rutvikrj26/openmuster/blob/main/deploy-scripts/deployment-info.json"
    click ZKModules "https://github.com/rutvikrj26/openmuster/blob/main/ignition/modules/Lock.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/config-overrides.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/config/env.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/config/getHttpsConfig.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/config/webpack.config.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/config/webpackDevServer.config.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/scripts/build.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/scripts/start.js"
    click UIBuild "https://github.com/rutvikrj26/openmuster/blob/main/scripts/test.js"
    click OldCLI "https://github.com/rutvikrj26/openmuster/blob/main/old/cli.js"
    click OldCLI "https://github.com/rutvikrj26/openmuster/blob/main/old/github-analyzer.js"
    click OldCLI "https://github.com/rutvikrj26/openmuster/blob/main/old/main.js"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef backend fill:#C3F9A6,stroke:#333,stroke-width:1px
    classDef blockchain fill:#F7C27B,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef devops fill:#D3D3D3,stroke:#333,stroke-width:1px
```
