How nehharshah/payments-distribution works
Project Type and Purpose
• This is a full-stack payment distribution system (“MCP Payment Distribution System”) that uses a Model Context Protocol (MCP) to compute and distribute stablecoin payments to open-source contributors.
• Key features:
• Contribution/time/milestone/reputation-weighted payments
• Smart-contract integration (Ethereum) via Web3.py and ethers.js
• PostgreSQL persistence with SQLAlchemy/Alembic
• React + TypeScript frontend with real-time Web3 data and Tailwind UI
File Structure Analysis
• Top-level directories:
• app/ – FastAPI backend
– app/core: business-logic modules (mcp, payment processor)
– app/models: database schema (SQLAlchemy)
– app/services: orchestrators (contribution tracker, payment service)
– alembic/: DB migration scripts
• frontend/ – Vite + React SPA
– src/api: axios/fetch wrappers for HTTP endpoints
– src/services/web3.ts: blockchain interactions (ethers.js)
– src/components/pages: UI elements and views
• lib/: smart-contract libraries (forge-std, OpenZeppelin) for Foundry
• docker-compose.yml: container definitions (API, DB, frontend)
• requirements.txt: Python dependencies (FastAPI, Web3.py, SQLAlchemy)
• Build & deployment:
• backend uses uvicorn, FastAPI; Alembic for migrations
• frontend uses Vite, Tailwind, React Query, Recharts
• Foundry (foundry.toml, remappings) for smart-contract compile/test
README Insights
• Tech stack sections confirm architectural boundaries and integrations.
a. Main Components
• Client Browser (React SPA)
• Frontend Container (Vite dev server / built assets served by CDN)
• API Server (FastAPI + uvicorn)
• Business Logic Layer
– MCP module (app/core/mcp.py)
– PaymentProcessor (app/core/payment_processor.py)
– ContributionTracker & PaymentService (app/services)
• Persistence Layer
– PostgreSQL (app/models/database.py)
– Alembic migrations
• Blockchain Layer
– Ethereum network
– Smart Contracts (compiled with Foundry + OpenZeppelin)
– Web3 interfaces (Web3.py on backend, ethers.js on frontend)
• External Services
– Stablecoin contracts (USDC, DAI, etc.)
– Wallet providers (MetaMask via web3-react)
b. Relationships & Data Flows
1. User → React UI → HTTP calls to FastAPI
2. FastAPI → Business Logic → Database reads/writes
3. FastAPI → Web3.py → Ethereum smart contracts (read state, send transactions)
4. Frontend Web3 (ethers.js) → Direct blockchain reads & wallet tx signing
5. Batch or scheduled jobs (ContributionTracker) → update contribution metrics
6. PaymentProcessor → triggers on-chain distribution transactions
c. Architectural Patterns & Principles
• Layered architecture: Presentation → API → Domain Services → Persistence/Blockchain
• Dependency inversion: core modules (mcp, payment_processor) unaware of HTTP or DB details
• Single responsibility: small services (contribution tracker, payment service)
• Infrastructure as code: Docker Compose for local orchestration
• Eventual consistency: on-chain state vs. DB state (track events in services)
• Frontend: React 18, TypeScript, Vite, Tailwind, Recharts, React Query
• Backend: FastAPI, uvicorn, SQLAlchemy, Alembic, Web3.py
• Blockchain: Foundry, forge-std, OpenZeppelin, Ethereum Test/MainNet
• Database: PostgreSQL