# mempool/mining-pools architecture

> Architecture diagram of the GitHub repository mempool/mining-pools, 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/mempool/mining-pools
- Repository: https://github.com/mempool/mining-pools

## Overview

##### Project type and purpose
- This is not a full-stack application but an open-source data repository for “mining pools” definitions.
- Its sole purpose is to maintain and validate JSON files (`pools-v2.json`, `pools.json`) that describe Bitcoin mining pools (names, links, regex tags, payout addresses).
- Downstream services (not in this repo) like the mempool backend fetch and use this data at runtime to tag blocks by pool.

##### File structure
- Top-level files
– LICENSE
– README.md (project description, contribution guide)
– pools.json (legacy list)
– pools-v2.json (authoritative, JSON schema with coinbase_tags, payout_addresses, slugs)
– dupes.sh (helper script to detect duplicates)
- .github/workflows/validate-json.yml
– CI pipeline to lint/validate JSON after each commit.
- No source code—this repo is purely data + validation.

##### README for additional insights
- Describes how to add or update mining pools, slug conventions, regex matching logic, payout address matching.
- Points to mempool backend code that:
– Fetches latest JSON on startup (configurable URLs)
– Parses regexes to assign blocks to pools
– Optionally re-indexes blocks when JSON changes
- Provides examples and guidance for contributors.

##### Elements
- Clear labels for each component (GitHub Repo, CI Pipeline, Backend Fetcher, Pools-Parser, DB, API, Frontend)
– commit → CI → merge
– backend startup → fetch JSON
– parser → database
– API → frontend
– Backend components in another
– Frontend/UI in yet another

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External actors
    Developer["Developer"]:::external
    EndUser["End User"]:::external

    %% GitHub Repository and CI
    subgraph "GitHub Repository"
        RepoRoot["GitHub Repo (data source)"]:::github
        Readme["README.md"]:::github
        License["LICENSE"]:::github
        LegacyJSON["pools.json"]:::github
        AuthoritativeJSON["pools-v2.json"]:::github
        DupScript["dupes.sh"]:::github
    end

    subgraph "Continuous Integration"
        CIWorkflow["validate-json.yml<br/>(GitHub Actions CI)"]:::ci
    end

    Developer -->|commit changes| RepoRoot
    RepoRoot -->|trigger on push/PR| CIWorkflow
    CIWorkflow -->|validate JSON & dupes| RepoRoot

    %% Mempool Backend
    subgraph "Mempool Backend"
        Fetcher["Backend Fetcher"]:::backend
        Parser["Pools-Parser"]:::backend
        Reindexer["Re-indexer"]:::backend
        API["API Layer"]:::backend
        DB["Database"]:::database
    end

    %% Data fetch from GitHub
    Fetcher -->|HTTPS fetch raw JSON| AuthoritativeJSON
    Fetcher --> Parser

    Parser -->|write assignments| DB
    Reindexer -->|re-assign blocks| DB
    API -->|read pool data| DB

    %% Frontend
    subgraph "Mempool Frontend"
        FrontendUI["Frontend UI"]:::frontend
    end

    API -->|REST API| FrontendUI
    FrontendUI -->|view data| EndUser

    %% Classes
    classDef github fill:#D0E6FF,stroke:#000;
    classDef ci fill:#E0FFFF,stroke:#000;
    classDef backend fill:#DFFFE0,stroke:#000;
    classDef database fill:#FFEB99,stroke:#000;
    classDef frontend fill:#FFD0D0,stroke:#000;
    classDef external fill:#CCCCCC,stroke:#000;

    %% Click Events
    click RepoRoot "https://github.com/mempool/mining-pools/tree/master//"
    click Readme "https://github.com/mempool/mining-pools/blob/master//README.md"
    click License "https://github.com/mempool/mining-pools/tree/master//LICENSE"
    click LegacyJSON "https://github.com/mempool/mining-pools/blob/master//pools.json"
    click AuthoritativeJSON "https://github.com/mempool/mining-pools/blob/master//pools-v2.json"
    click DupScript "https://github.com/mempool/mining-pools/blob/master//dupes.sh"
    click CIWorkflow "https://github.com/mempool/mining-pools/blob/master//.github/workflows/validate-json.yml"
```
