# ethereum/pm architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/pm
- Repository: https://github.com/ethereum/pm

## Overview

##### Project type and purpose
- This is primarily a documentation‐heavy “protocol meetings archive” repository with an embedded automation tool (“ACDbot”) under `.github/ACDbot`.
- ACDbot is a Python CLI application that fetches meeting metadata (from Google Calendar, Zoom, YouTube, etc.), processes transcripts and recordings, and publishes updates via GitHub, Discord, email, Telegram, Farcaster, Discourse, and an RSS feed.
- The rest of the repo is a static archive of Markdown meeting notes and process guidelines.

##### Top‐level components
- Orchestration (GitHub Actions workflows in `.github/workflows`)
- Application code (ACDbot Python package under `.github/ACDbot/`)
– `cli.py` (entry point)
– `modules/` (plugin‐style modules for each external service)
– `scripts/` (higher‐level scripts wiring modules to tasks)
– `meeting_topic_mapping.json`, `pyproject.toml`, `requirements.txt` (config & dependencies)
- Data storage
– Markdown meeting archives (e.g. `AllCoreDevs-EL-Meetings/`, `AllCoreDevs-CL-Meetings/`, `Breakout-Room-Meetings/`, etc.)
– `processes/` docs
- External services
– Google Calendar API, Zoom API, YouTube API
– Discord (webhook), Telegram, Farcaster, Discourse, email SMTP
– RSS feed generator

##### Key interactions and data flows
- A GitHub Action (e.g. `zoom-transcript-poll.yml`, `rss-feed-generator.yml`, `discord-notify.yml`, etc.) triggers on schedule or issue events.
- The workflow checks out the repo and invokes ACDbot CLI or specific `scripts/*.py`.
- ACDbot loads configuration, then calls one or more modules:
- `gcal` to fetch upcoming meeting info
- `zoom` to poll recordings and transcripts
- `youtube_utils` to refresh/upload recordings
- `transcript` to assemble or clean text
- `rss_utils` to rebuild the public RSS feed
…and notifies channels via `discord_notify`, `tg`, `email_utils`, `farcaster`, or posts to `discourse`.
- After processing, ACDbot writes updated Markdown notes or metadata into the meeting‐archive directories and commits them back to GitHub.
- The workflow then pushes any changes back to the repository, automatically updating the static archive.

##### Architectural patterns and design principles
- Modular “plugin” architecture: each external service has its own module under `modules/`.
- Scripts orchestrate modules per task, but the core CLI can also be used interactively.
- Event‐driven CI/CD: GitHub Actions as the scheduler and orchestrator.
- Clear separation of concerns between fetching data, processing it, and publishing notifications or repository updates.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Orchestration Layer"
        GHWF["GitHub Actions<br/>(Workflows)"]:::orchestration
    end

    subgraph "Application Layer"
        subgraph "Configuration"
            Pyproj["pyproject.toml"]:::config
            Req["requirements.txt"]:::config
            Mapping["meeting_topic_mapping.json"]:::config
        end
        CLI["ACDbot CLI (cli.py)"]:::app

        subgraph "Plugin Layer"
            GCal["GCal Module"]:::plugin
            ZoomM["Zoom Module"]:::plugin
            YT["YouTube Utils"]:::plugin
            Trans["Transcript Module"]:::plugin
            RSSMod["RSS Utils"]:::plugin
            DiscordM["Discord Notify"]:::plugin
            TG["Telegram Module"]:::plugin
            EmailM["Email Utils"]:::plugin
            Farc["Farcaster Module"]:::plugin
            Disc["Discourse Module"]:::plugin
        end

        subgraph "Scripts"
            SN["discord_notify.py"]:::script
            PZ["poll_zoom_recordings.py"]:::script
            UZ["upload_zoom_recording.py"]:::script
            SE["send_recording_email.py"]:::script
            SR["serve_rss.py"]:::script
            HI["handle_issue.py"]:::script
            GRT["get_refresh_token.py"]:::script
            GZT["get_zoom_token.py"]:::script
            RYT["refresh_youtube_token.py"]:::script
        end
    end

    subgraph "Data Layer"
        Markdown[(Meeting Archives)]:::data
        Processes[(processes/ docs)]:::data
        README["README.md"]:::data
    end

    subgraph "External Services"
        GC["Google Calendar API"]:::external
        Zm["Zoom API"]:::external
        YTapi["YouTube API"]:::external
        DiscWS["Discord Webhook"]:::external
        TgWS["Telegram"]:::external
        EmailS["Email SMTP"]:::external
        FarcWS["Farcaster"]:::external
        DiscService["Discourse"]:::external
        RSSfeed["RSS Consumers"]:::external
    end

    %% Connections
    GHWF -->|"triggers"| CLI
    CLI -->|"loads config"| Pyproj
    CLI -->|"loads config"| Req
    CLI -->|"loads config"| Mapping

    CLI -->|"calls"| GCal
    CLI -->|"calls"| ZoomM
    CLI -->|"calls"| YT
    CLI -->|"calls"| Trans
    CLI -->|"calls"| RSSMod
    CLI -->|"calls"| DiscordM
    CLI -->|"calls"| TG
    CLI -->|"calls"| EmailM
    CLI -->|"calls"| Farc
    CLI -->|"calls"| Disc

    CLI -->|"runs script"| SN
    CLI -->|"runs script"| PZ
    CLI -->|"runs script"| UZ
    CLI -->|"runs script"| SE
    CLI -->|"runs script"| SR
    CLI -->|"runs script"| HI
    CLI -->|"runs script"| GRT
    CLI -->|"runs script"| GZT
    CLI -->|"runs script"| RYT

    GCal -->|"fetches events"| GC
    ZoomM -->|"polls recordings"| Zm
    YT -->|"uploads/refreshes"| YTapi
    Trans -->|"processes transcripts"| Zm
    Trans -->|"processes transcripts"| GC
    RSSMod -->|"reads markdown"| Markdown
    RSSMod -->|"generates feed"| RSSfeed

    GCal -->|"writes metadata"| Markdown
    ZoomM -->|"writes transcripts"| Markdown
    YT -->|"writes recordings"| Markdown
    Trans -->|"writes cleaned text"| Markdown
    CLI -->|"commits & pushes"| Markdown

    DiscordM -->|"posts message"| DiscWS
    TG -->|"sends message"| TgWS
    EmailM -->|"sends email"| EmailS
    Farc -->|"posts update"| FarcWS
    Disc -->|"creates post"| DiscService

    %% Click Events
    click GHWF "https://github.com/ethereum/pm/tree/master/.github/workflows/"
    click CLI "https://github.com/ethereum/pm/blob/master/.github/ACDbot/cli.py"
    click Pyproj "https://github.com/ethereum/pm/blob/master/.github/ACDbot/pyproject.toml"
    click Req "https://github.com/ethereum/pm/blob/master/.github/ACDbot/requirements.txt"
    click Mapping "https://github.com/ethereum/pm/blob/master/.github/ACDbot/meeting_topic_mapping.json"
    click GCal "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/gcal.py"
    click ZoomM "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/zoom.py"
    click YT "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/youtube_utils.py"
    click Trans "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/transcript.py"
    click RSSMod "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/rss_utils.py"
    click DiscordM "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/discord_notify.py"
    click TG "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/tg.py"
    click EmailM "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/email_utils.py"
    click Farc "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/farcaster.py"
    click Disc "https://github.com/ethereum/pm/blob/master/.github/ACDbot/modules/discourse.py"
    click SN "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/discord_notify.py"
    click PZ "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/poll_zoom_recordings.py"
    click UZ "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/upload_zoom_recording.py"
    click SE "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/send_recording_email.py"
    click SR "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/serve_rss.py"
    click HI "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/handle_issue.py"
    click GRT "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/get_refresh_token.py"
    click GZT "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/get_zoom_token.py"
    click RYT "https://github.com/ethereum/pm/blob/master/.github/ACDbot/scripts/refresh_youtube_token.py"
    click README "https://github.com/ethereum/pm/blob/master/README.md"
    click Processes "https://github.com/ethereum/pm/tree/master/processes/"

    %% Styles
    classDef orchestration fill:#D6E9F8,stroke:#4A90E2
    classDef app fill:#E8F5E9,stroke:#2E7D32
    classDef plugin fill:#C8E6C9,stroke:#388E3C
    classDef script fill:#DCEDC8,stroke:#558B2F
    classDef config fill:#FFF9C4,stroke:#FBC02D
    classDef data fill:#D7CCC8,stroke:#6D4C41
    classDef external fill:#ECEFF1,stroke:#90A4AE
```
