# blockopsnetwork/telescope architecture

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

- Interactive diagram: https://gitdiagram.com/blockopsnetwork/telescope
- Repository: https://github.com/blockopsnetwork/telescope

## Overview

##### Key Architectural Domains

a. User Input & Configuration
– Represent both the command‐line interface (CLI) and YAML configuration file components (the “telescope_config.yaml”) as the entry point.
– Include “configuration management” to parse options for servers, metrics, logs, and integrations.

b. Core Runtime & Processing Engine
– Show the “core engine” that orchestrates the overall functionality. Telescope’s internal packages (e.g. the “internal” directory with subpackages like agentseed, boringcrypto, flow, converter, etc.) indicate that a modular, component‐based design is in use.
– Highlight the subsystems for metrics and logs processing, conversion, and pipeline orchestration.
– Emphasize that it supports different pipelines via components (for example, using elements from internal/component that contain integrations for Loki, otelcol exporters, and discovery components).

c. Metrics Pipeline
– Detail the components that manage metric scraping, write-ahead logging (“WAL_directory”), transformation, and remote write operations.
– Specify that metrics are collected (via configured “scrape_configs” that target blockchain node endpoints like “localhost:8545”), aggregated, and then forwarded remotely (using the “remote_write” configuration).

d. Logs Pipeline
– Represent the logs configuration pathway that collects log streams and positions (for instance, using a positions file to keep track of logs read) and sends them to an external log sink (such as a Loki instance).
– Include conversion modules and client libraries (from internal/component/loki) that prepare and push logs.

e. Integrations & Third-party Exports
– Show that Telescope integrates with external systems (e.g., node exporter, blockchain nodes, remote monitoring services, etc.).
– Include integration components such as the “agent” (which may be toggled on/off) and third-party modules which are embedded in the internal/integrations directories.

f. Web UI and Dashboard
– Display the Web UI component (stored in “internal/web/ui”) that serves dashboards and visualization.
– Associate this with both the operator (cmd/agent-operator) and the server components (internal/service/http and internal/web) that manage API endpoints for user interactions.

##### Interactions and Data Flows

– Show a split from the core engine into two main pipelines: the Metrics Pipeline and Logs Pipeline.
- In the Metrics Pipeline, show data flow from “scrape_configs” (data harvested from blockchain nodes) through the WAL buffer, then processing/transformation components, and finally outbound to the remote_write endpoints.
- In the Logs Pipeline, represent log collection, conversion, and position tracking before logs are sent to the configured logs sink (like a Loki service).
– Connect the pipelines to external endpoints such as blockchain nodes (data sources), remote write servers (e.g., Prometheus-compatible endpoints), and log sinks (Loki endpoints).

##### Architectural Patterns and Technologies

– Indicate that protocols and interfaces (such as HTTP endpoints and basic authentication) play a key role.
– Include language notes (Golang) and mention used technologies: for example, references to OpenTelemetry components (otelcol), Prometheus remote write standards for metrics, and Loki for log aggregation.

##### Final Suggestions

– Ensure all essential elements from the file tree—such as the “cmd” directories (for executable entry points), “internal” packages (showing modular decomposition), “dashboards”, and “tools” (for operational support)—are at least conceptually represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input & Configuration
    subgraph "User Input & Configuration"
        CI["Configuration Input (CLI & YAML)"]:::config
        YAML["YAML Config"]:::config
        CLI_A["CLI Agent"]:::config
        CLI_OP["CLI Operator"]:::config
        YAML --> CI
        CLI_A --> CI
        CLI_OP --> CI
    end

    %% Core Runtime & Processing Engine
    subgraph "Core Runtime & Processing Engine"
        CORE["Core Engine / Orchestrator"]:::core
        FLOW["Flow Orchestration"]:::core
        CORE --> FLOW
    end

    CI --> CORE

    %% Metrics Pipeline
    subgraph "Metrics Pipeline"
        BLOCK["Blockchain Node Endpoints"]:::external
        MS["Metrics Scraper & RemoteWrite"]:::pipeline
        WAL["WAL Buffer"]:::pipeline
        CONV["Metrics Converter"]:::pipeline
        BLOCK --> MS
        MS --> WAL
        WAL --> CONV
    end

    FLOW --> MS

    %% Logs Pipeline
    subgraph "Logs Pipeline"
        LC["Log Collector & Positions Tracker"]:::pipeline
        LPROC["Log Processor & Converter"]:::pipeline
        LOKI["Loki Log Sink"]:::external
        LC --> LPROC
        LPROC --> LOKI
    end

    CORE --> LC

    %% Integrations & Third-party Exports
    subgraph "Integrations & Third-party Exports"
        DISC["Discovery & Integrations"]:::integration
        OTEL["Otel Collector Integration"]:::integration
        INTTEST["Integration Tests"]:::integration
        DISC --> INTTEST
    end

    CORE --> DISC
    CORE --> OTEL

    %% Web UI and Dashboard
    subgraph "Web UI and Dashboard"
        HS["HTTP Server"]:::ui
        WA["Web API Endpoint"]:::ui
        UI["Web UI Dashboard"]:::ui
        HS --> WA
        WA --> UI
    end

    CORE --> HS

    %% Click Events
    click YAML "https://github.com/blockopsnetwork/telescope/blob/main/telescope_config.yaml"
    click CLI_A "https://github.com/blockopsnetwork/telescope/tree/main/cmd/agent"
    click CLI_OP "https://github.com/blockopsnetwork/telescope/tree/main/cmd/agent-operator"
    click CORE "https://github.com/blockopsnetwork/telescope/tree/main/internal/"
    click FLOW "https://github.com/blockopsnetwork/telescope/tree/main/internal/flow/"
    click MS "https://github.com/blockopsnetwork/telescope/tree/main/internal/component/prometheus/remotewrite/"
    click WAL "https://github.com/blockopsnetwork/telescope/tree/main/internal/component/common/loki/wal/"
    click CONV "https://github.com/blockopsnetwork/telescope/tree/main/internal/converter/"
    click LC "https://github.com/blockopsnetwork/telescope/tree/main/internal/component/common/loki/positions/"
    click LPROC "https://github.com/blockopsnetwork/telescope/tree/main/internal/component/common/loki/client/"
    click DISC "https://github.com/blockopsnetwork/telescope/tree/main/internal/component/discovery/"
    click OTEL "https://github.com/blockopsnetwork/telescope/tree/main/internal/component/otelcol/"
    click INTTEST "https://github.com/blockopsnetwork/telescope/tree/main/internal/cmd/integration-tests/"
    click HS "https://github.com/blockopsnetwork/telescope/tree/main/internal/service/http/"
    click WA "https://github.com/blockopsnetwork/telescope/tree/main/internal/web/api/"
    click UI "https://github.com/blockopsnetwork/telescope/tree/main/internal/web/ui/"

    %% Styles
    classDef config fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef core fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef pipeline fill:#d3ffd3,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef integration fill:#ffdead,stroke:#000,stroke-width:1px;
    classDef ui fill:#87CEFA,stroke:#000,stroke-width:1px;
```
