# aws/clock-bound architecture

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

- Interactive diagram: https://gitdiagram.com/aws/clock-bound
- Repository: https://github.com/aws/clock-bound

## Overview

##### Main Components

a) ClockBound Daemon (clock-bound-d)
- This as a central component
- Subcomponents:
- Chrony Poller
- SHM Writer
- Thread Manager
- Signal Handler

b) Shared Memory Interface
- This as an intermediate layer between daemon and clients
- Shared memory header structure

c) Client Libraries
- Two official clients:
- Rust Client (clock-bound-client)
- C Client (clock-bound-ffi)
- Potential custom clients

d) External Components
- Chrony daemon (NTP service)
- System clock
- Amazon Time Sync Service (optional external reference)

##### Relationships and Data Flow

- Chrony daemon → ClockBound Daemon (polling)
- ClockBound Daemon → Shared Memory (writing)
- Clients → Shared Memory (reading)
- Amazon Time Sync Service → Chrony daemon

##### Technical Details

Important elements:
- Clock Error Bound calculation formula
- Shared memory protocol details
- Component responsibilities:
- Daemon: Time polling, error calculation, SHM management
- Clients: Reading bounded timestamps
- Shared Memory: Data structure for timestamp exchange

##### Additional Elements

Include:
- Notes about error bound calculations
- Protocol version information
- Licensing information for different components

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External
        AWS["Amazon Time Sync Service"]:::external
        SysClock["System Clock"]:::system
    end

    subgraph TimeService
        Chrony["Chrony Daemon (NTP)"]:::external
    end

    subgraph DaemonLayer["ClockBound Daemon"]
        Daemon["clock-bound-d"]:::daemon
        CPoller["Chrony Poller"]:::daemon
        SWriter["SHM Writer"]:::daemon
        TManager["Thread Manager"]:::daemon
        SHandler["Signal Handler"]:::daemon
        FSM["Clock State FSM"]:::daemon
    end

    subgraph SHMLayer["Shared Memory Interface"]
        SHMHeader["SHM Header"]:::shm
        SHMReader["SHM Reader"]:::shm
        SHMCommon["Common SHM Functions"]:::shm
        SHMWriter["SHM Writer"]:::shm
    end

    subgraph ClientLayer["Client Libraries"]
        RustClient["Rust Client"]:::client
        CClient["C Client (FFI)"]:::client
        CustomClient["Custom Clients"]:::client
    end

    %% Connections
    AWS --> Chrony
    Chrony --> CPoller
    SysClock --> Daemon
    
    %% Daemon Internal
    Daemon --> CPoller
    Daemon --> SWriter
    Daemon --> TManager
    Daemon --> SHandler
    SWriter --> FSM
    
    %% SHM Connections
    FSM --> SHMWriter
    SHMWriter --> SHMHeader
    SHMReader --> SHMHeader
    SHMWriter & SHMReader --> SHMCommon
    
    %% Client Connections
    RustClient & CClient & CustomClient --> SHMReader

    %% Styling
    classDef external fill:#90EE90
    classDef system fill:#D3D3D3
    classDef daemon fill:#ADD8E6
    classDef shm fill:#FFD700
    classDef client fill:#87CEEB

    %% Click Events
    click Daemon "https://github.com/aws/clock-bound/blob/main/clock-bound-d/src/main.rs"
    click CPoller "https://github.com/aws/clock-bound/blob/main/clock-bound-d/src/chrony_poller.rs"
    click SWriter "https://github.com/aws/clock-bound/blob/main/clock-bound-d/src/shm_writer.rs"
    click TManager "https://github.com/aws/clock-bound/blob/main/clock-bound-d/src/thread_manager.rs"
    click SHandler "https://github.com/aws/clock-bound/blob/main/clock-bound-d/src/signal.rs"
    click FSM "https://github.com/aws/clock-bound/blob/main/clock-bound-d/src/shm_writer/clock_state_fsm.rs"
    click SHMHeader "https://github.com/aws/clock-bound/blob/main/clock-bound-shm/src/shm_header.rs"
    click SHMReader "https://github.com/aws/clock-bound/blob/main/clock-bound-shm/src/reader.rs"
    click SHMWriter "https://github.com/aws/clock-bound/blob/main/clock-bound-shm/src/writer.rs"
    click SHMCommon "https://github.com/aws/clock-bound/blob/main/clock-bound-shm/src/common.rs"
    click RustClient "https://github.com/aws/clock-bound/blob/main/clock-bound-client/src/lib.rs"
    click CClient "https://github.com/aws/clock-bound/tree/main/clock-bound-ffi"
```
