# astraly-labs/pragma-common architecture

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

- Interactive diagram: https://gitdiagram.com/astraly-labs/pragma-common
- Repository: https://github.com/astraly-labs/pragma-common

## Overview

##### Project type and purpose
- This is a Rust “common” library crate (“Pragma Common”) that provides shared data types, helpers, and service-level abstractions for other Pragma Rust libraries. It is not a standalone service or executable but a collection of modules for on-chain data handling (Ethereum, Starknet), telemetry, and Protobuf-based definitions.

##### File structure
Top-level items:
- Cargo.toml / build.rs – defines crate metadata, dependencies, and invokes Protobuf code-gen
- schema/entries.proto – Protobuf definitions for various “entry” types
- src/
– aggregation.rs – aggregation utilities
– entries/… – entry types: price, volume, orderbook, open_interest, funding_rate
– pair/… – trading pair helpers
– instrument_type.rs, interval.rs – enums for instruments & time intervals
– services.rs – core service abstractions (e.g., fetching, processing entries)
– web3/… – Ethereum client wrappers
– starknet/… – Starknet client wrappers, typed data, network errors
– telemetry/… – metrics & tracing instrumentation
– task_group.rs – task orchestration helpers
- tests/ – unit tests for Protobuf and service modules
- .github/, Makefile, taplo/ – CI, build scripts, formatting

##### Key insights from README
- “Common utilities and types used in Pragma rust libraries” – confirms that this crate is a shared module set. No runtime “system” of its own; its value lies in the modules it exposes and how they interconnect.

a. Main components to show
- Protobuf Schema & Code Generator (build.rs)
- Core Domain Types (entries, pair, instrument_type, interval)
- Service Layer (services.rs, aggregation.rs)
- Blockchain Clients:
– Ethereum/Web3 module
– Starknet module
- Telemetry Module
- Task Orchestrator (task_group)
- Consumers (downstream Pragma applications or other crates)

b. Relationships & interactions
–  Protobuf schema → build.rs → generated entry types → core domain types
–  Service Layer invokes blockchain clients (web3, starknet) to fetch on-chain data
–  Service Layer emits metrics/traces via Telemetry Module
–  Task Orchestrator coordinates asynchronous calls through the Service Layer
–  Downstream crates import public APIs from this library

c. Architectural patterns & design principles
– Modular separation: domain types vs. service logic vs. infra clients vs. telemetry
– Dependency inversion: service layer depends on abstract traits of web3/starknet clients
– Code-gen boundary: Protobuf definitions isolated from hand-written code
– Single Responsibility: each module has a clear focus

d. Key technologies and libraries
– Rust (Cargo, build.rs)
– Protocol Buffers (schema/entries.proto)
– Async HTTP/JSON-RPC (web3 module)
– Starknet Typed Data & network errors
– OpenTelemetry or metrics crates (telemetry module)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Code Generation
    subgraph "Code Generation"
        schema["entries.proto"]:::codegen
        build["build.rs"]:::codegen
    end
    schema -->|"defines messages"| build

    %% Core Domain Types
    subgraph "Core Domain Types"
        subgraph "Entries Module"
            entries_mod["mod.rs"]:::domain
            price["price.rs"]:::domain
            volume["volume.rs"]:::domain
            orderbook["orderbook.rs"]:::domain
            open_interest["open_interest.rs"]:::domain
            funding_rate["funding_rate.rs"]:::domain
        end
        pair_mod["pair/mod.rs"]:::domain
        instrument["instrument_type.rs"]:::domain
        interval["interval.rs"]:::domain
    end
    build -->|"generates types"| entries_mod
    entries_mod --> price
    entries_mod --> volume
    entries_mod --> orderbook
    entries_mod --> open_interest
    entries_mod --> funding_rate

    %% Service Layer
    subgraph "Service Layer"
        services["services.rs"]:::domain
        aggregation["aggregation.rs"]:::domain
    end
    entries_mod -->|"uses entry types"| services
    pair_mod -->|"pair helpers"| services
    instrument -->|"enum definitions"| services
    interval -->|"enum definitions"| services
    aggregation --> services

    %% Blockchain Clients
    subgraph "Blockchain Clients"
        subgraph "Ethereum/Web3"
            web3_mod["web3/mod.rs"]:::infra
            chain["web3/chain.rs"]:::infra
            token_mod["web3/token/mod.rs"]:::infra
            token_consts["web3/token/constants.rs"]:::infra
        end
        subgraph "Starknet"
            stark_mod["starknet/mod.rs"]:::infra
            network["starknet/network.rs"]:::infra
            errors["starknet/errors.rs"]:::infra
            typed_data["starknet/typed_data.rs"]:::infra
        end
    end
    services -->|"fetch on-chain data"| web3_mod
    services -->|"fetch on-chain data"| stark_mod
    web3_mod --> chain
    web3_mod --> token_mod
    token_mod --> token_consts
    stark_mod --> network
    stark_mod --> errors
    stark_mod --> typed_data

    %% Telemetry Module
    telemetry["telemetry/mod.rs"]:::telemetry
    services -->|"emit metrics/traces"| telemetry

    %% Task Orchestrator
    task_group["task_group.rs"]:::domain
    task_group --> services

    %% Consumers
    consumers["Downstream Crates"]:::external
    consumers -->|"import public APIs"| services
    consumers -->|"invoke task orchestrator"| task_group

    %% Click Events
    click schema "https://github.com/astraly-labs/pragma-common/blob/main/schema/entries.proto"
    click build "https://github.com/astraly-labs/pragma-common/blob/main/build.rs"
    click entries_mod "https://github.com/astraly-labs/pragma-common/blob/main/src/entries/mod.rs"
    click price "https://github.com/astraly-labs/pragma-common/blob/main/src/entries/price.rs"
    click volume "https://github.com/astraly-labs/pragma-common/blob/main/src/entries/volume.rs"
    click orderbook "https://github.com/astraly-labs/pragma-common/blob/main/src/entries/orderbook.rs"
    click open_interest "https://github.com/astraly-labs/pragma-common/blob/main/src/entries/open_interest.rs"
    click funding_rate "https://github.com/astraly-labs/pragma-common/blob/main/src/entries/funding_rate.rs"
    click pair_mod "https://github.com/astraly-labs/pragma-common/blob/main/src/pair/mod.rs"
    click instrument "https://github.com/astraly-labs/pragma-common/blob/main/src/instrument_type.rs"
    click interval "https://github.com/astraly-labs/pragma-common/blob/main/src/interval.rs"
    click services "https://github.com/astraly-labs/pragma-common/blob/main/src/services.rs"
    click aggregation "https://github.com/astraly-labs/pragma-common/blob/main/src/aggregation.rs"
    click web3_mod "https://github.com/astraly-labs/pragma-common/blob/main/src/web3/mod.rs"
    click chain "https://github.com/astraly-labs/pragma-common/blob/main/src/web3/chain.rs"
    click token_mod "https://github.com/astraly-labs/pragma-common/blob/main/src/web3/token/mod.rs"
    click token_consts "https://github.com/astraly-labs/pragma-common/blob/main/src/web3/token/constants.rs"
    click stark_mod "https://github.com/astraly-labs/pragma-common/blob/main/src/starknet/mod.rs"
    click network "https://github.com/astraly-labs/pragma-common/blob/main/src/starknet/network.rs"
    click errors "https://github.com/astraly-labs/pragma-common/blob/main/src/starknet/errors.rs"
    click typed_data "https://github.com/astraly-labs/pragma-common/blob/main/src/starknet/typed_data.rs"
    click telemetry "https://github.com/astraly-labs/pragma-common/blob/main/src/telemetry/mod.rs"
    click task_group "https://github.com/astraly-labs/pragma-common/blob/main/src/task_group.rs"

    %% Styles
    classDef codegen fill:#ADD8E6,stroke:#000,color:#000
    classDef domain fill:#90EE90,stroke:#000,color:#000
    classDef infra fill:#FFA500,stroke:#000,color:#000
    classDef telemetry fill:#DDA0DD,stroke:#000,color:#000
    classDef external fill:#D3D3D3,stroke:#000,color:#000
```
