# torproject/metrics-lib architecture

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

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

## Overview

##### Main Components
- Descriptor Sources: Represent the various origins (cached data, directory authorities/mirrors, file system resources) from which descriptors are fetched.
- Descriptor Fetcher/Reader: The API’s component responsible for reading raw descriptor data. Look at classes like DescriptorReader, DescriptorSourceFactory, and their corresponding implementations.
- Descriptor Parser: This segment interprets the raw descriptor content. Include classes like DescriptorParser and its implementation (DescriptorParserImpl) to show that it converts data into structured objects.
- Descriptor Types & Implementations: Various descriptor types (relay, bridge, extra info, log descriptors, microdescriptors, etc.) each having both interface/base classes (in the main package) and concrete implementations (in the impl package).
- Indexing and Logging: Separate packages handle indexing (org.torproject.descriptor.index) and logging (org.torproject.descriptor.log), indicating components for management of descriptor metadata and operational logs.
- OnionPerf and Additional Analysis: Components specific to performance metrics and analysis are represented in the onionperf package.

##### Relationships and Data Flow
- A flow from Descriptor Reader to Descriptor Parser, which interprets the content.
- That the Parser feeds results into the Descriptor Store from where client applications can query descriptor data.
- For descriptor types, you might want to branch out from the abstract Descriptor node into various concrete implementations (RelayDescriptor, BridgeDescriptor, etc.).

##### Architectural Patterns & Design Principles
- Use of abstraction. For example, show that the “Descriptor” is an interface or abstract class, and then branch out to several implementations. This illustrates the principle of programming to an interface.
- Where the Factory pattern is applied (the DescriptorSourceFactory) and any other significant design patterns like Singleton (if used) or Adapter.

##### Technologies and Key Artifacts
- A “Resources/Examples” block, indicating that tutorial examples (from src/main/resources/examples) and documentation (README, overview.html) are part of the supporting ecosystem.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Descriptor Acquisition Block
    subgraph "Descriptor Acquisition"
        A1["DescriptorSourceFactory"]:::source
        A2["Directory Source Entry"]:::source
        A3["Directory Source Entry Impl"]:::source
    end

    %% Descriptor Fetching Block
    subgraph "Descriptor Fetching"
        B1["DescriptorReader"]:::fetcher
        B2["DescriptorReaderImpl"]:::fetcher
    end

    %% Descriptor Parsing Block
    subgraph "Descriptor Parsing"
        C1["DescriptorParser"]:::parser
        C2["DescriptorParserImpl"]:::parser
    end

    %% Descriptor Types Block
    subgraph "Descriptor Types"
        D1["Descriptor Interface"]:::types
        D2["DescriptorImpl"]:::types
    end

    %% Descriptor Storage
    E["Descriptor Store"]:::store

    %% Indexing Block
    subgraph "Indexing"
        F1["DescriptorIndexCollector"]:::indexer
    end

    %% Logging Block
    subgraph "Logging"
        G1["LogDescriptorImpl"]:::logger
    end

    %% OnionPerf & Analysis Block
    subgraph "OnionPerf & Analysis"
        H1["OnionPerf Analysis"]:::analysis
    end

    %% Testing & Benchmarking Block
    subgraph "Testing & Benchmarking"
        I1["DescriptorTest"]:::testing
        I2["MeasurePerformance"]:::testing
    end

    %% API Facade Block
    subgraph "API Facade"
        J1["DescriptorCollector"]:::facade
    end

    %% Build & CI Block
    subgraph "Build & CI"
        K1["build.xml"]:::build
        K2[".gitlab-ci.yml"]:::build
    end

    %% Data Flow Connections
    A1 -->|"creates"| B1
    A2 --> B1
    A3 --> B1

    B1 -->|"reads_raw"| C1
    B2 --> C1

    C1 -->|"parses"| E
    C2 --> E

    C1 -->|"produces_typed"| D1
    D1 -->|"stored_as_object"| E

    E -->|"provided_to"| J1

    %% Logging and Indexing
    B1 -->|"logs"| G1
    C1 -->|"logs"| G1
    E -->|"indexes"| F1

    %% OnionPerf Analysis
    E -->|"analysis_data"| H1

    %% API Orchestration
    J1 -->|"orchestrates"| B1

    %% Testing & Benchmarking
    I1 -->|"validates_store"| E
    I2 -->|"benchmarks_store"| E

    %% Styles for better visual differentiation
    classDef source fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef fetcher fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef parser fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef types fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef store fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef indexer fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef logger fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef analysis fill:#EAF2F8,stroke:#2471A3,stroke-width:2px;
    classDef testing fill:#F5EEF8,stroke:#8E44AD,stroke-width:2px;
    classDef facade fill:#E8F8F5,stroke:#1ABC9C,stroke-width:2px;
    classDef build fill:#FEF9E7,stroke:#F39C12,stroke-width:2px;

    %% Click Events for Component Mapping
    click A1 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/DescriptorSourceFactory.java"
    click A2 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/DirSourceEntry.java"
    click A3 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/impl/DirSourceEntryImpl.java"

    click B1 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/DescriptorReader.java"
    click B2 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/impl/DescriptorReaderImpl.java"

    click C1 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/DescriptorParser.java"
    click C2 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/impl/DescriptorParserImpl.java"

    click D1 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/Descriptor.java"
    click D2 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/impl/DescriptorImpl.java"

    click F1 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/index/DescriptorIndexCollector.java"
    click G1 "https://github.com/torproject/metrics-lib/blob/master/src/main/java/org/torproject/descriptor/log/LogDescriptorImpl.java"
    click H1 "https://github.com/torproject/metrics-lib/tree/master/src/main/java/org/torproject/descriptor/onionperf"

    click I1 "https://github.com/torproject/metrics-lib/blob/master/src/test/java/org/torproject/descriptor/DescriptorTest.java"
    click I2 "https://github.com/torproject/metrics-lib/blob/master/src/test/java/org/torproject/descriptor/benchmark/MeasurePerformance.java"
```
