# lowlighter/metrics architecture

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

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

## Overview

##### Main components of the system
- Core Application: This is implemented in the “source/app” directory and is divided into sub-components:
- Action Runner (“source/app/action”): Handles execution as a GitHub Action, triggered by workflows.
- Metrics Processor (“source/app/metrics”): This module aggregates data by invoking plugins, processing GitHub API responses (both GraphQL and REST), and applying business logic.
- Web Server (“source/app/web”): Serves the rendered metrics images and static assets (JS, CSS, HTML) for embedding and viewing.
- Plugins Module: Located in “source/plugins”, it includes many individual plugins (for achievements, activity, languages, stargazers, etc.). Each plugin contains logic (often in ES modules) plus GraphQL query files that encapsulate specific functionality. This forms the extensibility point of the architecture.
- Templates Engine: Found in “source/templates” with several sub-folders such as “classic”, “repository”, “terminal”, and “markdown”. These templates (using EJS and CSS) define the visual layout of the generated metrics.
- CI/CD and Deployment:
- GitHub Actions and workflows (under .github/workflows and .github/actions) where automated builds, tests, releases, and even cleaning scripts are defined.
- Docker integration (via Dockerfile and Docker-related scripts) and deployment configuration (vercel.json) indicating multiple deployment strategies including self-hosting and shared instances.
- Configuration & Metadata:
- Several configuration files (e.g., package.json, settings.example.json, .editorconfig, ARCHITECTURE.md) support the overall setup, linting, build, and deployment processes.

##### Relationships and interactions
- When running, the GitHub Action (or a direct command via CLI/Docker) triggers the Metrics Processor. This module calls various plugin modules to retrieve GitHub analytics data by using GitHub APIs (both REST and GraphQL).
- The aggregated data is then fed into the templating engine. Depending on the template chosen (classic, repository, terminal, markdown, or community), the templating engine renders the final metrics as SVG or HTML.
- The Web Server sub-component serves these rendered assets as static files that can be embedded or viewed directly by users.
- CI/CD components (GitHub Actions workflows, scripts under .github/scripts, and Docker setups) automatically test, build, and deploy the code and templates.
- The plugin system allows easy extensibility: new plugins can be added into the “source/plugins” directory, and each follows a similar structure (e.g., index.mjs, metadata.yml, queries directory) indicating a standardized plugin contract.

##### Important architectural patterns and technologies
- Modular Plugin Architecture: The plugins are loosely coupled, and the core system dynamically loads these modules at runtime.
- Template/Renderer Pattern: The separation between content (the raw metrics data) and appearance (templates) enables customization and theming.
- CI/CD Integration: The repository is well-integrated with GitHub Actions for continuous testing, code quality, and deployment.
- Technology Stack: The project is based on Node.js (using ES modules, .mjs files), uses Docker for containerization, and leverages GitHub’s API (both REST and GraphQL) extensively.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core Application Subgraph
    subgraph "Core Application"
        AR["Action Runner"]:::core
        MP["Metrics Processor"]:::core
        WS["Web Server"]:::core
    end

    %% External Modules
    PM["Plugins Module"]:::plugin
    TE["Templates Engine"]:::template
    EA["External APIs (GitHub REST/GraphQL & ThirdParty)"]:::external

    %% CI/CD & Deployment Subgraph
    subgraph "CI/CD & Deployment"
        CI1["GitHub Actions Workflows"]:::cicd
        CI2["GitHub Actions Scripts"]:::cicd
        DKR["Docker Integration"]:::cicd
        VERCEL["Deployment Config"]:::cicd
    end

    %% Configuration & Metadata Subgraph
    subgraph "Configuration & Metadata"
        PKG["package.json"]:::config
        PKG_LOCK["package-lock.json"]:::config
        SETTINGS["settings.example.json"]:::config
        EDITOR[".editorconfig"]:::config
        ARCH["ARCHITECTURE.md"]:::config
    end

    %% Data Flow Connections
    AR -->|"triggers"| MP
    MP -->|"calls"| PM
    MP -->|"fetches"| EA
    EA -->|"responds"| MP
    MP -->|"sends_data"| TE
    TE -->|"renders"| WS

    %% CI/CD interactions with Core Application
    CI1 ---|"deploys"| AR
    CI2 ---|"deploys"| AR
    DKR ---|"builds"| AR
    VERCEL ---|"deploys"| AR

    %% Configuration interactions
    PKG ---|"configures"| MP
    SETTINGS ---|"configures"| TE

    %% Styling Definitions
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef plugin fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef template fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef external fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef cicd fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef config fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;

    %% Click Events
    click AR "https://github.com/lowlighter/metrics/tree/master/source/app/action"
    click MP "https://github.com/lowlighter/metrics/tree/master/source/app/metrics"
    click WS "https://github.com/lowlighter/metrics/tree/master/source/app/web"
    click PM "https://github.com/lowlighter/metrics/tree/master/source/plugins"
    click TE "https://github.com/lowlighter/metrics/tree/master/source/templates"
    click CI1 "https://github.com/lowlighter/metrics/tree/master/.github/workflows"
    click CI2 "https://github.com/lowlighter/metrics/tree/master/.github/actions"
    click DKR "https://github.com/lowlighter/metrics/tree/master/Dockerfile"
    click VERCEL "https://github.com/lowlighter/metrics/blob/master/vercel.json"
    click PKG "https://github.com/lowlighter/metrics/blob/master/package.json"
    click PKG_LOCK "https://github.com/lowlighter/metrics/blob/master/package-lock.json"
    click SETTINGS "https://github.com/lowlighter/metrics/blob/master/settings.example.json"
    click EDITOR "https://github.com/lowlighter/metrics/blob/master/.editorconfig"
    click ARCH "https://github.com/lowlighter/metrics/blob/master/ARCHITECTURE.md"
```
