# erezgeva/libptpmgmt architecture

> Architecture diagram of the GitHub repository erezgeva/libptpmgmt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erezgeva/libptpmgmt
- Repository: https://github.com/erezgeva/libptpmgmt

## Overview

##### Project type and purpose
- This is a mono-repo for libptpmgmt:
- A core C++ library implementing IEEE-1588 PTP management messaging
- A thin C wrapper exposing a C API
- SWIG-based language bindings (Go, Python, Perl, Ruby, PHP, Lua, Tcl)
- Two CLI tools (pmc, phc_ctl) built on the library
- A ‘Clock Manager’ framework (clkmgr) that uses the library to monitor and configure local PTP clocks
- Sample applications, unit tests, system tests, packaging recipes and CI pipelines

##### File structure
- Top-level directories
- src/           — C++ implementation of messages, serialization, sockets, TLVs, utilities
- pub/           — C wrapper headers & wrapper glue for C API
- swig/          — SWIG interface files for Go
- wrappers/      — language-specific SWIG wrappers and test code
- clkmgr/        — Clock Manager code (client state, proxy, configuration)
- ptp-tools/     — pmc & phc_ctl CLI tool impls
- sample/, hmac/, uctest/, utest/ — sample apps and C/C++ unit tests
- tools/         — CI scripts, packaging helpers, code-style, release automation
- packaging dirs (debian/, rpm/, archlinux/, gentoo/)
- Build and config files (Makefile, configure.ac, .gitlab/ and .github/ workflows)

##### README for additional insights
- Core lib namespace: ptpmgmt (C wrapper prefixes: ptpmgmt_)
- Implements get/set/command of all management TLVs via UDP-IPv4/IPv6, Ethernet or Unix socket to ptp4l
- Library is data-oriented: structures + message builders/parsers
- SWIG wrappers generate idiomatic bindings per language
- Clock Manager uses the library to collect telemetry and expose an API to local apps
- pmc, phc_ctl are reference tools built on the library

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD and Packaging (dashed)
    subgraph "CI/CD & Packaging"
        direction TB
        CI["CI/CD Workflows"]:::dashed
        Debian["debian/"]:::dashed
        RPM["rpm/"]:::dashed
        Arch["archlinux/"]:::dashed
        Gentoo["gentoo/"]:::dashed
    end

    %% Library Layer
    subgraph "Library Layer"
        direction TB
        Core["libptpmgmt C++ core (src/)"]:::lib
        CAPI["C API wrapper (pub/, pub/c/)"]:::lib
        SWIGGo["SWIG Go binding (swig/go/)"]:::lib
        SWIGLang["SWIG language bindings (wrappers/)"]:::lib
    end

    %% Applications
    subgraph "Applications"
        direction TB
        CLI["CLI Tools (ptp-tools/)"]:::app
        ClkClient["Clock Manager Client (clkmgr/client/)"]:::app
        ClkSample["Clock Manager Samples (clkmgr/sample/)"]:::app
    end

    %% Services
    subgraph "Services"
        direction TB
        ClkProxy["Clock Manager Proxy (clkmgr/proxy/)"]:::service
        Ptp4l["ptp4l Daemon"]:::service
    end

    %% Tests & Samples
    subgraph "Quality & Samples"
        direction TB
        UCTestC["Core C Unit Tests (uctest/)"]:::dashed
        UTestCpp["Core C++ Unit Tests (utest/)"]:::dashed
        ClkUTest["Clock Manager Unit Tests (clkmgr/utest/)"]:::dashed
        SampleApp["General Samples (sample/)"]:::app
    end

    %% Automation Tools
    Tools["Automation Tools (tools/)"]:::dashed

    %% External Systems
    subgraph "External Systems"
        direction TB
        PTPNet["PTP Network (UDP/IPv4, UDP/IPv6, Ethernet)"]:::external
        UnixSock["Unix Socket to ptp4l"]:::external
    end

    %% Connections
    CI -->|drives builds| Core
    CI -->|drives packaging| Debian
    CI -->|drives packaging| RPM
    CI -->|drives packaging| Arch
    CI -->|drives packaging| Gentoo

    Tools --> CI
    Tools --> Debian
    Tools --> RPM
    Tools --> Arch
    Tools --> Gentoo

    CLI -->|uses C API| CAPI
    ClkClient -->|uses C API| CAPI
    ClkSample -->|uses C API| CAPI

    SWIGGo -->|wraps C API| CAPI
    SWIGLang -->|wraps C API| CAPI

    CAPI -->|built atop| Core

    ClkClient -->|in-process calls| ClkProxy
    ClkProxy -->|Unix socket| Ptp4l
    ClkProxy -->|uses Core| Core

    Core -->|sends/receives| PTPNet
    Core -->|sends/receives| UnixSock

    UCTestC -->|tests| CAPI
    UTestCpp -->|tests| Core
    ClkUTest -->|tests| ClkClient
    SampleApp -->|demo| Core

    %% Click Events
    click Core "https://github.com/erezgeva/libptpmgmt/tree/master/src/"
    click CAPI "https://github.com/erezgeva/libptpmgmt/tree/master/pub/"
    click SWIGGo "https://github.com/erezgeva/libptpmgmt/tree/master/swig/go/"
    click SWIGLang "https://github.com/erezgeva/libptpmgmt/tree/master/wrappers/"
    click CLI "https://github.com/erezgeva/libptpmgmt/tree/master/ptp-tools/"
    click ClkClient "https://github.com/erezgeva/libptpmgmt/tree/master/clkmgr/client/"
    click ClkProxy "https://github.com/erezgeva/libptpmgmt/tree/master/clkmgr/proxy/"
    click ClkSample "https://github.com/erezgeva/libptpmgmt/tree/master/clkmgr/sample/"
    click ClkUTest "https://github.com/erezgeva/libptpmgmt/tree/master/clkmgr/utest/"
    click UCTestC "https://github.com/erezgeva/libptpmgmt/tree/master/uctest/"
    click UTestCpp "https://github.com/erezgeva/libptpmgmt/tree/master/utest/"
    click SampleApp "https://github.com/erezgeva/libptpmgmt/tree/master/sample/"
    click CI "https://github.com/erezgeva/libptpmgmt/tree/master/.github/workflows/"
    click Debian "https://github.com/erezgeva/libptpmgmt/tree/master/debian/"
    click RPM "https://github.com/erezgeva/libptpmgmt/tree/master/rpm/"
    click Arch "https://github.com/erezgeva/libptpmgmt/tree/master/archlinux/"
    click Gentoo "https://github.com/erezgeva/libptpmgmt/tree/master/gentoo/"
    click Tools "https://github.com/erezgeva/libptpmgmt/tree/master/tools/"

    %% Styles
    classDef lib fill:#DCEEFB,stroke:#1E40AF;
    classDef app fill:#D1FADF,stroke:#059669;
    classDef service fill:#FEF3C7,stroke:#D97706;
    classDef external fill:#F3F4F6,stroke:#6B7280;
    classDef dashed fill:none,stroke:#9CA3AF,stroke-dasharray:5 5;
```
