# open-telemetry/opamp-go architecture

> Architecture diagram of the GitHub repository open-telemetry/opamp-go, 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/open-telemetry/opamp-go
- Repository: https://github.com/open-telemetry/opamp-go

## Overview

##### Project’s Type and Purpose
- This project implements the Open Agent Management Protocol (OpAMP) in Go. It is designed for remote management of large fleets of data collection agents, enabling agents to report status, receive configurations, and update packages.
- The repository is organized as both a client and a server implementation of the protocol alongside supporting libraries, certificate management, and examples. This indicates a dual-sided network protocol system architecture.

##### File Structure
- The top-level directories include:
- client – Implements OpAMP client-side logic. Contains modules for HTTP and WebSocket communication, internal helper packages, tests, and type definitions.
- server – Implements the server side of OpAMP. This directory includes files for managing HTTP connections, WebSocket communication, and callbacks.
- internal – Provides shared utilities such as certificate generation (certs), specification details (opamp-spec), examples (agent, server, supervisor), test helpers, and additional tools. The examples illustrate real-world usage and integration.
- protobufs & protobufshelpers – Contain the generated and helper code based on Protobuf definitions for serializing the OpAMP message exchange.
- The existence of build configurations (GitHub workflows, makefile) and configuration files (e.g., for certificates) highlight deployment and security aspects.

##### Main Components and Their Interactions
a. Client Component:
- Located in the client directory.
- Contains modules for HTTP and WebSocket clients (client.go, httpclient.go, wsclient.go), type definitions (in client/types), and several internal utilities to handle message processing, package synchronization, and state management.
b. Server Component:
- Located in the server directory.
- Implements server logic (server.go, serverimpl.go) and connection management both for HTTP and WebSocket protocols.
c. Shared Infrastructure and Utilities:
- The internal directory offers common utilities such as certificate management (for TLS security), logging (noplogger.go), retry logic (retryafter.go), and opamp protocol specifics (opamp-spec).
- Test helpers and examples help illustrate and validate interactions between components.
d. Communication Interfaces:
- Data exchange and control messages are structured based on Protobufs (in the protobufs directory).
- The design likely supports multiple communication channels (HTTP and WebSocket) to ensure flexibility in agent-server interactions.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The clear separation between client and server indicates well-defined roles. The use of internal directories for utility functions and supporting libraries underlines modularity.
- Protocol Abstraction: Utilizing Protobufs (with generated PB code) encapsulates the protocol message definitions, making communication between agents and server standardized.
- Testability and Mocking: The presence of numerous _test.go files and internal test helpers ensure that components are testable and follow dependency injection practices.
- Security Emphasis: The certificate management setup in internal/certs implies that secure communication (TLS) is a critical design element.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Agent-side)"
        direction TB
        A["HTTP Client"]:::client
        B["WebSocket Client"]:::client
        C["Internal Client Utilities & Types"]:::client
    end

    %% Protocol Layer
    subgraph "OpAMP Protocol Layer"
        direction TB
        P["Protobuf-based Protocol"]:::protocol
    end

    %% Server Side
    subgraph "Server"
        direction TB
        D["HTTP Connection Manager"]:::server
        E["WebSocket Connection Manager"]:::server
        F["Server Implementation & Callbacks"]:::server
    end

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        G["Certificate Management (TLS)"]:::security
        H["Shared Utilities & Infrastructure"]:::utility
        I["Examples (agent, server, supervisor)"]:::example
        J["Test Utilities"]:::example
    end

    %% Connections between Client and Protocol Layer
    A -->|"OpAMPMessageExchange"| P
    B -->|"OpAMPMessageExchange"| P
    C -->|"UsesUtilities"| P

    %% Connections between Protocol Layer and Server
    P -->|"OpAMPMessageExchange"| D
    P -->|"OpAMPMessageExchange"| E
    P -->|"CallbackHandling"| F

    %% Direct Connection between Client and Server endpoints
    A ---|"DirectHTTP"| D
    B ---|"DirectWS"| E

    %% Certificate Management interacts with Client and Server
    G --- A
    G --- B
    G --- D
    G --- E

    %% Shared Utilities interacts with Client and Server Implementation
    H --- C
    H --- F

    %% Examples and Test Utilities interactions
    I --- C
    I --- F
    J --- C
    J --- F

    %% Click Events for Component Mapping
    click A "https://github.com/open-telemetry/opamp-go/tree/main/client/"
    click B "https://github.com/open-telemetry/opamp-go/tree/main/client/"
    click C "https://github.com/open-telemetry/opamp-go/tree/main/client/"
    click D "https://github.com/open-telemetry/opamp-go/tree/main/server/"
    click E "https://github.com/open-telemetry/opamp-go/tree/main/server/"
    click F "https://github.com/open-telemetry/opamp-go/tree/main/server/"
    click G "https://github.com/open-telemetry/opamp-go/tree/main/internal/certs"
    click P "https://github.com/open-telemetry/opamp-go/tree/main/protobufs/"
    click H "https://github.com/open-telemetry/opamp-go/tree/main/internal/"
    click I "https://github.com/open-telemetry/opamp-go/tree/main/internal/examples/"
    click J "https://github.com/open-telemetry/opamp-go/tree/main/internal/testhelpers/"

    %% Styling
    classDef client fill:#cce5ff,stroke:#287bde,stroke-width:2px;
    classDef server fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef protocol fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef security fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef utility fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef example fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
