# nehharshah/payments-distribution architecture

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

- Interactive diagram: https://gitdiagram.com/nehharshah/payments-distribution
- Repository: https://github.com/nehharshah/payments-distribution

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Tier"
        direction TB
        ClientBrowser["React SPA<br/>(React, TypeScript)"]:::ui
        FrontendContainer["Vite Dev Server / CDN Assets"]:::ui
        FEAPIWrappers["HTTP API Wrappers<br/>(axios/fetch)"]:::ui
        FEWeb3["Web3 Interface<br/>(ethers.js)"]:::ui
    end

    subgraph "Backend Tier"
        direction TB
        APIServer["FastAPI Server<br/>(uvicorn)"]:::api
        subgraph "Business Logic"
            direction TB
            MCP["MCP Module"]:::api
            PaymentProcessor["Payment Processor"]:::api
            ContributionTracker["Contribution Tracker Service"]:::api
            PaymentService["Payment Service"]:::api
        end
    end

    subgraph "Data & DevOps"
        direction TB
        Postgres["PostgreSQL"]:::db
        Alembic["Alembic Migrations"]:::db
        Requirements["requirements.txt"]:::ext
        DockerCompose["Docker Compose"]:::ext
        Env["Environment Configs"]:::ext
        Readme["README & Docs"]:::ext
    end

    subgraph "Blockchain Layer"
        direction TB
        Ethereum["Ethereum Network"]:::chain
        SmartContracts["Smart Contracts"]:::chain
        Foundry["Foundry Toolchain"]:::chain
    end

    %% Connections
    ClientBrowser -->|"HTTP/JSON"| APIServer
    FEAPIWrappers -.->|wrappers| APIServer
    FEWeb3 -->|"JSON-RPC"| Ethereum

    APIServer -->|"calls"| MCP
    APIServer -->|"calls"| PaymentProcessor
    APIServer -->|"reads/writes"| Postgres
    MCP -->|"SQL"| Postgres
    PaymentProcessor -->|"tx"/Ethereum| Ethereum

    ContributionTracker -->|"metrics update"| Postgres
    ContributionTracker -->|"triggers tx"| Ethereum
    PaymentService -->|"batch distribution"| Ethereum

    Alembic -->|"migrations"| Postgres
    DockerCompose --> APIServer
    DockerCompose --> Postgres
    DockerCompose --> FrontendContainer
    Env --> APIServer
    Env --> FrontendContainer
    Foundry --> SmartContracts
    Readme --> DockerCompose

    %% Click Events
    click ClientBrowser "https://github.com/nehharshah/payments-distribution/tree/main/frontend/src/"
    click FrontendContainer "https://github.com/nehharshah/payments-distribution/blob/main/frontend/package.json"
    click FrontendContainer "https://github.com/nehharshah/payments-distribution/blob/main/frontend/vite.config.ts"
    click FEAPIWrappers "https://github.com/nehharshah/payments-distribution/blob/main/frontend/src/api/dashboard.ts"
    click FEAPIWrappers "https://github.com/nehharshah/payments-distribution/blob/main/frontend/src/api/projects.ts"
    click FEWeb3 "https://github.com/nehharshah/payments-distribution/blob/main/frontend/src/services/web3.ts"
    click APIServer "https://github.com/nehharshah/payments-distribution/blob/main/app/main.py"
    click APIServer "https://github.com/nehharshah/payments-distribution/blob/main/requirements.txt"
    click MCP "https://github.com/nehharshah/payments-distribution/blob/main/app/core/mcp.py"
    click PaymentProcessor "https://github.com/nehharshah/payments-distribution/blob/main/app/core/payment_processor.py"
    click ContributionTracker "https://github.com/nehharshah/payments-distribution/blob/main/app/services/contribution_tracker.py"
    click PaymentService "https://github.com/nehharshah/payments-distribution/blob/main/app/services/payment_service.py"
    click Postgres "https://github.com/nehharshah/payments-distribution/blob/main/app/models/database.py"
    click Alembic "https://github.com/nehharshah/payments-distribution/tree/main/alembic/"
    click SmartContracts "https://github.com/nehharshah/payments-distribution/tree/main/lib/forge-std/"
    click SmartContracts "https://github.com/nehharshah/payments-distribution/tree/main/lib/openzeppelin-contracts/"
    click DockerCompose "https://github.com/nehharshah/payments-distribution/blob/main/docker-compose.yml"
    click Foundry "https://github.com/nehharshah/payments-distribution/blob/main/foundry.toml"
    click Env "https://github.com/nehharshah/payments-distribution/blob/main/.env.example"
    click Env "https://github.com/nehharshah/payments-distribution/blob/main/frontend/.env.example"
    click Readme "https://github.com/nehharshah/payments-distribution/blob/main/README.md"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#0366d6;
    classDef api fill:#d4edda,stroke:#155724;
    classDef db fill:#fff3cd,stroke:#856404;
    classDef chain fill:#e2e3ff,stroke:#4b0082;
    classDef ext fill:#f8f9fa,stroke:#6c757d;
```
