# github/issue-metrics architecture

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

- Interactive diagram: https://gitdiagram.com/github/issue-metrics
- Repository: https://github.com/github/issue-metrics

## Overview

##### Project type and purpose
- This is an open-source GitHub Action written in Python.
- Purpose: run inside a GitHub Actions workflow (or as a container), query issues/PRs/discussions via the GitHub API, compute a set of temporal and participation metrics, render a report (Markdown or JSON), and post it back to GitHub as an issue.

##### High-level file-structure analysis
- Top level:
- action.yml (defines inputs/outputs/entrypoint)
- Dockerfile (builds a Python environment)
- Python scripts (auth.py, config.py, search.py, issue_metrics.py, metric modules, writer modules)
- . github/workflows & docs (CI, linting, examples)
- tests (one per module)
- Pattern: a linear pipeline—authenticate, fetch data, compute metrics (plug-in modules), write output.

##### Key README insights
- Describes supported authentication modes (GitHub App vs PAT).
- Lists available metrics (each implemented in its own module).
- Shows the two-step workflow:
a) ‘Run issue-metrics tool’
b) ‘Create issue’ from the generated file using a separate Action.

##### Components
a. Main components:
1) GitHub Actions Host (runner VM)
2) Container / Python runtime (built via Dockerfile)
3) Entry point (action.yml → Python CLI invocation)
4) Config loader (config.py reads inputs & env vars)
5) Auth module (auth.py handles App vs PAT)
6) Query module (search.py, discussions.py fetch paginated data via GitHub REST API)
7) Metrics pipeline: individual modules (time_to_first_response.py, time_to_close.py, time_in_label.py, most_active_mentors.py, etc.)
8) Report formatters (json_writer.py, markdown_writer.py + markdown_helpers.py)
9) Output artifact (issue_metrics.md or .json)
10) Issue creation step (peter-evans/create-issue-from-file Action)
11) External service: GitHub REST API
b. Relationships & interactions:
- The runner spins up the container → entrypoint loads config → auth module obtains credentials → query module streams events → each metric module consumes the event stream → writers aggregate results → output file → second Action uses API to create/update the issue.
c. Architectural patterns & principles:
- Modular “plugin” pattern for metrics (one file per metric).
- Separation of concerns: auth, config, data fetch, computation, formatting.
- “Pipeline” data flow.
d. Key technologies/frameworks:
- Python 3.10+, requests or PyGitHub for API calls.
- Docker container for runtime isolation.
- GitHub Actions inputs/outputs via action.yml.
- CI/CD: GitHub workflows for linting, testing, publishing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment
    Runner(("GitHub Actions Host")):::external
    Runner --> Container

    Container[/Container / Python Runtime/]:::container
    click Container "https://github.com/github/issue-metrics/tree/main/Dockerfile"

    %% Entrypoint
    EntrypointAction["action.yml (Action Definition)"]:::core
    click EntrypointAction "https://github.com/github/issue-metrics/blob/main/action.yml"
    EntrypointCLI["issue_metrics.py (CLI)"]:::core
    click EntrypointCLI "https://github.com/github/issue-metrics/blob/main/issue_metrics.py"
    Container --> EntrypointAction --> EntrypointCLI

    %% Configuration & Auth
    Config["config.py"]:::core
    click Config "https://github.com/github/issue-metrics/blob/main/config.py"
    EntrypointCLI --> Config

    Auth["auth.py"]:::core
    click Auth "https://github.com/github/issue-metrics/blob/main/auth.py"
    Config --> Auth

    %% Data Fetch
    subgraph "Query Modules"
        direction TB
        Search["search.py"]:::core
        click Search "https://github.com/github/issue-metrics/blob/main/search.py"
        Discussions["discussions.py"]:::core
        click Discussions "https://github.com/github/issue-metrics/blob/main/discussions.py"
        Labels["labels.py"]:::core
        click Labels "https://github.com/github/issue-metrics/blob/main/labels.py"
    end
    Auth --> Search
    Auth --> Discussions
    Auth --> Labels
    Search --> Classes
    Discussions --> Classes
    Labels --> Classes

    Classes["classes.py"]:::core
    click Classes "https://github.com/github/issue-metrics/blob/main/classes.py"

    %% Metrics Pipeline
    subgraph "Metrics Modules"
        direction TB
        TTFResponse["time_to_first_response.py"]:::pipeline
        click TTFResponse "https://github.com/github/issue-metrics/blob/main/time_to_first_response.py"
        TClose["time_to_close.py"]:::pipeline
        click TClose "https://github.com/github/issue-metrics/blob/main/time_to_close.py"
        TAnswer["time_to_answer.py"]:::pipeline
        click TAnswer "https://github.com/github/issue-metrics/blob/main/time_to_answer.py"
        TMerge["time_to_merge.py"]:::pipeline
        click TMerge "https://github.com/github/issue-metrics/blob/main/time_to_merge.py"
        TRReady["time_to_ready_for_review.py"]:::pipeline
        click TRReady "https://github.com/github/issue-metrics/blob/main/time_to_ready_for_review.py"
        TDraft["time_in_draft.py"]:::pipeline
        click TDraft "https://github.com/github/issue-metrics/blob/main/time_in_draft.py"
        Mentors["most_active_mentors.py"]:::pipeline
        click Mentors "https://github.com/github/issue-metrics/blob/main/most_active_mentors.py"
    end
    Classes --> TTFResponse
    Classes --> TClose
    Classes --> TAnswer
    Classes --> TMerge
    Classes --> TRReady
    Classes --> TDraft
    Classes --> Mentors

    %% Report Formatters
    subgraph "Report Formatters"
        direction TB
        JSONW["json_writer.py"]:::core
        click JSONW "https://github.com/github/issue-metrics/blob/main/json_writer.py"
        MDW["markdown_writer.py"]:::core
        click MDW "https://github.com/github/issue-metrics/blob/main/markdown_writer.py"
        MDH["markdown_helpers.py"]:::core
        click MDH "https://github.com/github/issue-metrics/blob/main/markdown_helpers.py"
    end
    TTFResponse --> JSONW
    TClose --> JSONW
    TAnswer --> JSONW
    TMerge --> JSONW
    TRReady --> JSONW
    TDraft --> JSONW
    Mentors --> JSONW
    JSONW --> Output
    MDW --> Output
    MDH --> MDW

    Output[/issue_metrics.md or .json/]:::output
    click Output "https://github.com/github/issue-metrics/blob/main/issue_metrics.md"
    JSONW --> Output

    %% Issue Creation
    IssueCreate(("peter-evans/create-issue-from-file")):::external
    Output --> IssueCreate

    %% External API
    GitHubAPI[(GitHub REST API)]:::external
    Search -->|REST| GitHubAPI
    Discussions -->|REST| GitHubAPI
    Labels -->|REST| GitHubAPI
    IssueCreate -->|REST| GitHubAPI

    %% CI / Tests / Docs
    subgraph "CI/CD & Quality"
        direction TB
        CI[".github/workflows/*.yml"]:::external
        click CI "https://github.com/github/issue-metrics/blob/main/.github/workflows/docker-image.yml"
        click CI "https://github.com/github/issue-metrics/blob/main/.github/workflows/python-package.yml"
        click CI "https://github.com/github/issue-metrics/blob/main/.github/workflows/linter.yaml"
        Tests["test_*.py"]:::external
        click Tests "https://github.com/github/issue-metrics/blob/main/test_*.py"
    end

    subgraph Documentation
        Docs["docs/"]:::external
        click Docs "https://github.com/github/issue-metrics/tree/main/docs/"
    end

    Runner --> CI
    CI --> Container
    Runner --> Tests
    Runner --> Docs

    %% Styles
    classDef container fill:#CEEFFF,stroke:#0066CC;
    classDef core fill:#cce5ff,stroke:#004080;
    classDef pipeline fill:#e6ccff,stroke:#6600cc;
    classDef external fill:#ccffcc,stroke:#008000;
    classDef output fill:#fff3cd,stroke:#ffcc00;
```
