# openbb-finance/openbb-metricsv2 architecture

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

- Interactive diagram: https://gitdiagram.com/openbb-finance/openbb-metricsv2
- Repository: https://github.com/openbb-finance/openbb-metricsv2

## Overview

##### Project type and purpose
- This is a small open-source metrics-collection tool written in Python.
- It runs as a scheduled GitHub Action (cron) every 12 hours to fetch usage and engagement metrics from external services (YouTube, Discord, PyPI, etc.) and writes them into a JSON file (`metrics.json`).
- There is no user-facing frontend; it’s essentially a lightweight ETL/data-ingest pipeline triggered by GitHub Actions.

##### File structure
- Top level:
– `.github/workflows/metrics-runner.yml` → defines the scheduled GitHub Action
– `main.py` → orchestrator script
– `metrics.json` → target output file
– `pyproject.toml` / `requirements.txt` → dependency & packaging info
- `utilities/` package:
– `config.py` → loads environment variables (API keys, tokens) from `.env`
– `helpers.py` → contains the actual functions that call each external API and transform the responses

##### README for additional insights
- Describes setup (pip install, .env) and execution (`python main.py`)
- Confirms the schedule (GitHub Action runs every 12 hours)
- Identifies the external platforms (YouTube, Discord, PyPI, …)

a. Main components:
– Scheduler (GitHub Actions cron job)
– Runner Environment (the VM/container that executes the workflow)
– Python Application:
- Entry point: `main.py`
- Configuration layer: `utilities/config.py`
- Metric collectors: functions in `utilities/helpers.py`
– External Services/APIs (YouTube Data API, Discord API, PyPI API, etc.)
– Output Store: `metrics.json` in the repo (or artifact storage)

b. Relationships & data flows:
1. GitHub Actions scheduler triggers at 00:00 and 12:00 UTC
2. Action spins up a runner environment, checks out the code
3. Runner loads environment variables from `.env` via `config.py`
4. `main.py` calls helper functions to fetch from each API
5. Responses are aggregated and written to `metrics.json`
6. (Optionally) the workflow commits/pushes the updated `metrics.json` back to the repo

c. Architectural patterns & principles:
– Modular utilities (config vs. helpers vs. orchestrator)
– Single responsibility: each helper method targets one external service
– ETL-style pipeline: Extract (API calls), Transform (normalize), Load (write JSON)

d. Key technologies/frameworks:
– Python 3.x (entry point `main.py`)
– dotenv or python-decouple (in `utilities/config.py`)
– requests or specialized SDKs (in `utilities/helpers.py`)
– GitHub Actions (YAML workflow)
– JSON output (`metrics.json`)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Scheduler and Runner
    Scheduler["GitHub Actions Scheduler (cron)"]:::gh
    Scheduler --> Runner["Runner VM/Container"]:::gh

    %% Workflow Steps
    subgraph "Workflow Steps"
        direction TB
        Checkout["Checkout Code"]:::gh
        SetupPy["Setup Python Environment"]:::gh
        LoadCfg["Load Config (.env)"]:::py
        RunOrch["Run Orchestrator Script"]:::py
        Commit["Commit metrics.json"]:::gh
    end

    Runner --> Checkout
    Checkout --> SetupPy
    SetupPy --> LoadCfg
    LoadCfg --> RunOrch
    RunOrch --> Commit

    %% Orchestrator and Modules
    RunOrch --> Main["main.py"]:::py
    Main --> Config["utilities/config.py"]:::py
    Main --> Helpers["utilities/helpers.py"]:::py

    %% External Services
    subgraph "External APIs"
        direction TB
        YT["YouTube Data API"]:::ext
        Discord["Discord API"]:::ext
        PyPI["PyPI API"]:::ext
    end

    Helpers --> YT
    Helpers --> Discord
    Helpers --> PyPI

    %% Output Store
    Helpers --> Metrics["metrics.json"]:::store

    %% Repository Files
    subgraph "Repository Files"
        direction TB
        PyProj["pyproject.toml"]:::doc
        ReqTxt["requirements.txt"]:::doc
        Readme["README.md"]:::doc
    end

    Checkout --> PyProj
    Checkout --> ReqTxt
    Checkout --> Readme

    %% Click Events
    click Scheduler "https://github.com/openbb-finance/openbb-metricsv2/blob/main/.github/workflows/metrics-runner.yml"
    click Main "https://github.com/openbb-finance/openbb-metricsv2/blob/main/main.py"
    click Config "https://github.com/openbb-finance/openbb-metricsv2/blob/main/utilities/config.py"
    click Helpers "https://github.com/openbb-finance/openbb-metricsv2/blob/main/utilities/helpers.py"
    click Metrics "https://github.com/openbb-finance/openbb-metricsv2/blob/main/metrics.json"
    click PyProj "https://github.com/openbb-finance/openbb-metricsv2/blob/main/pyproject.toml"
    click ReqTxt "https://github.com/openbb-finance/openbb-metricsv2/blob/main/requirements.txt"
    click Readme "https://github.com/openbb-finance/openbb-metricsv2/blob/main/README.md"

    %% Styles
    classDef gh fill:#0366d6,stroke:#024ea2,color:#fff;
    classDef py fill:#2d8fdd,stroke:#1b6fa8,color:#fff;
    classDef ext fill:#f08d49,stroke:#d17c37,color:#fff;
    classDef store fill:#6a737d,stroke:#52565c,color:#fff;
    classDef doc fill:#6f42c1,stroke:#593185,color:#fff;
```
