# electron/download-stats architecture

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

- Interactive diagram: https://gitdiagram.com/electron/download-stats
- Repository: https://github.com/electron/download-stats

## Overview

##### Project Type and Purpose
- This is a backend‐only data‐pipeline project written in Node.js. Its purpose is to automatically fetch, process, and publish download statistics for Electron (both npm package downloads and GitHub release asset downloads). It is driven by scheduled GitHub Actions and outputs JSON under `data/` and a summary table in the README.

##### File Structure Analysis
- Top-level scripts:
- fetch-data.js – retrieves npm download stats via the npm registry API
- fetch-releases.js – retrieves raw GitHub asset download counts via the GitHub Releases API
- releases.js – helper to normalize release tags and metadata
- index.js – aggregates and formats the fetched data for presentation
- Data storage:
- data/ – versioned JSON snapshots (one file per Electron release line)
- CI/CD and configuration:
- .github/workflows/schedule.yml – cron schedule to run fetch scripts
- .github/workflows/lint.yml – linting checks on code
- dependabot.yml, .prettierrc – maintenance/config files
- Package management:
- package.json / package-lock.json – Node dependencies and script definitions

##### README Insights
- Describes two main metrics: average daily npm downloads by month, and raw GitHub asset download counts per release.
- Indicates that data is refreshed via a scheduled GitHub Action (`schedule.yml`).

a. Main Components
- Scheduler (GitHub Actions runner)
- Data Fetcher scripts (Node.js environment)
- External APIs:
– npm registry API
– GitHub Releases API
- Processing modules:
– fetch-data.js
– fetch-releases.js
– releases.js
– index.js
- Data Store: Git repository (data/ JSON files)
- Output: README table, raw JSON files

b. Relationships & Interactions
1. Scheduler triggers workflow on a cron schedule.
2. Workflow spins up Node.js runner, checks out repo.
3. Runner executes fetch-data.js → calls npm API → writes JSON to data/npm-*.json
4. Runner executes fetch-releases.js → calls GitHub API → writes JSON to data/electron-*.json
5. Runner runs index.js → consolidates JSON files → updates README table or generates summary artifacts.
6. Runner commits/pushes updated JSON and README back to the repo.

c. Architectural Patterns & Principles
- Periodic batch processing (ETL style)
- Separation of concerns: data fetching vs. data normalization vs. data aggregation
- Infrastructure as code: GitHub Actions defining the entire run environment and schedule
- Storage as code: JSON files versioned in Git instead of a database

d. Key Technologies & Libraries
- Node.js (JavaScript runtime)
- Axios or native fetch (HTTP requests to external APIs)
- GitHub Actions for CI/CD scheduling
- npm registry API, GitHub REST API
- JSON as storage format

##### Final Advice
- Every logical component (scheduler, runner, fetcher, processor, store, output).
- This level of detail will give stakeholders a crystal-clear view of the data pipeline architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Control Plane
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        Scheduler["Scheduler (Cron)"]:::ciComp
        Lint["Lint Workflow"]:::ciComp
        Dependabot["Dependabot Config"]:::ciComp
        Runner["Runner (Node.js)"]:::internal
    end

    %% Data Plane
    subgraph "Data Plane"
        direction TB
        FD["fetch-data.js"]:::internal
        FR["fetch-releases.js"]:::internal
        RM["releases.js"]:::internal
        IDX["index.js"]:::internal
        DS["Data Store (data/)"]:::internal
        OUT["README summary table"]:::internal
    end

    %% Repository Configuration
    subgraph "Repository"
        direction TB
        PKG["package.json / package-lock.json"]:::config
        PRE[".prettierrc"]:::config
    end

    %% External Services
    NPMA["npm registry API"]:::external
    GHA["GitHub Releases API"]:::external

    %% Flow Relationships
    Scheduler -->|triggers| Runner
    Runner --> FD
    Runner --> FR
    Runner --> IDX

    FD -->|calls npm registry| NPMA
    FD -->|writes JSON| DS

    FR -->|calls GitHub API| GHA
    FR -->|writes JSON| DS
    FR --> RM

    IDX -->|reads JSON| DS
    IDX --> RM
    IDX -->|updates README| OUT

    Runner -->|commits updates| DS
    Runner -->|commits updates| OUT
    Runner -->|uses| PKG
    Runner -->|uses| PRE

    %% Click Events
    click Scheduler "https://github.com/electron/download-stats/blob/main/.github/workflows/schedule.yml"
    click Lint "https://github.com/electron/download-stats/blob/main/.github/workflows/lint.yml"
    click Dependabot "https://github.com/electron/download-stats/blob/main/.github/dependabot.yml"
    click FD "https://github.com/electron/download-stats/blob/main/fetch-data.js"
    click FR "https://github.com/electron/download-stats/blob/main/fetch-releases.js"
    click RM "https://github.com/electron/download-stats/blob/main/releases.js"
    click IDX "https://github.com/electron/download-stats/blob/main/index.js"
    click DS "https://github.com/electron/download-stats/tree/main/data/"
    click OUT "https://github.com/electron/download-stats/blob/main/readme.md"
    click PKG "https://github.com/electron/download-stats/blob/main/package.json"
    click PKG "https://github.com/electron/download-stats/blob/main/package-lock.json"
    click PRE "https://github.com/electron/download-stats/blob/main/.prettierrc"

    %% Styles
    classDef internal fill:#E3F2FD,stroke:#2196F3
    classDef external fill:#E8F5E9,stroke:#4CAF50
    classDef config fill:#F3E5F5,stroke:#9C27B0
    classDef ciComp fill:#FFF3E0,stroke:#FB8C00,stroke-dasharray:5 5
```
