# mlichvar/chrony architecture

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

- Interactive diagram: https://gitdiagram.com/mlichvar/chrony
- Repository: https://github.com/mlichvar/chrony

## Overview

##### Project Type and Purpose
- chrony is a system‐level time‐synchronization suite implementing NTPv4 (RFC 5905).
- It consists of:
- chronyd – the long‐running daemon that synchronises the system clock
- chronyc – the CLI client for monitoring and controlling chronyd
- It runs on Unix‐like OSes (Linux, FreeBSD, macOS, illumos), interfaces with network servers and hardware reference clocks, and applies advanced filtering/smoothing algorithms.

##### File Structure Analysis and Architectural Implications
- Top‐level:
- source files (.c/.h) implement virtually every subsystem
- configure/Makefile.in for build system (autoconf)
- doc/ and examples/ for user docs and sample configs
- test/ for unit, system, simulation, kernel‐interface tests
- Key subsystems visible in file names:
- Network I/O: ntp_io*.c, socket.c
- Protocol core: ntp_core.c, ntp_ext.c, ntp_auth.c, pktlength.c
- Security: NTS (nts_ke_*.c, nts_ntp_*.c), legacy NTP‐auth (keys.c)
- Time‐discipline: samplefilt.c / array.c / smooth.c / sched.c / sources.c
- Reference clocks: refclock_*.c, local*.c, hwclock.c, rtc_*.c
- System abstraction: sys_*.c (Linux, macOS, POSIX, Solaris, NetBSD), memory.c, logging.c
- CLI/Control: cmdparse.c / cmdmon.c, client.c (chronyc), clientlog.c
- Configuration: conf.c, addressing.c / addrfilt.c
- Persistence: leapdb.c, driftfile via conf
- Utility/crypto primitives: hash_*.c, cmac_*.c, siv_*.c, md5.c, getdate.*
- The project follows a layered modular architecture:
- OS abstraction layer
- Crypto & helper libraries
- Protocol stack
- Time‐discipline engine
- Device/clock drivers
- CLI & control interface
- Persistence & logging

- Confirms dual‐program architecture (daemon + CLI).
- Emphasis on network, reference clocks, NTP servers, and peer mode.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External entities
    NTPServ["NTP Servers/Peers"]:::external
    GPS["Hardware Clocks"]:::external
    ChronyClient["chronyc"]:::service

    %% CLI Client
    subgraph "CLI Client"
        ChronyClient
    end

    %% Daemon and subsystems
    subgraph "Daemon (chronyd)"
        ChronyDaemon["chronyd"]:::service
        CMD["Commands (cmdparse & cmdmon)"]:::service
        Config["Configuration"]:::config
        Logging["Logging & Monitoring"]:::logging
        NetIO["Network I/O"]:::net
        Prot["Protocol Engine"]:::core
        Sec["Security & Auth"]:::security
        TDCore["Time-discipline Core"]:::core
        Ref["Reference Clock Drivers"]:::driver
        OS["System Clock & OS Abstraction"]:::driver
        Persist["Persistence (drift & leap DB)"]:::storage
    end

    %% Relationships
    ChronyClient -->|"IPC/socket"| ChronyDaemon
    ChronyDaemon --> CMD
    ChronyDaemon --> Config
    ChronyDaemon --> Logging
    CMD -->|parse commands| Config
    Config -->|init parameters| Prot
    Config -->|init parameters| Sec
    Config -->|init parameters| TDCore
    Logging -->|writes logs| Persist
    NTPServ -->|UDP 123 NTPv4 packets| NetIO
    NetIO -->|packets| Prot
    Sec -->|decrypt/auth| Prot
    Prot -->|validated packets| TDCore
    TDCore -->|adjust clock| OS
    GPS --> Ref
    Ref -->|time samples| TDCore
    Persist -->|reads/writes| Config
    Persist -->|reads/writes| ChronyDaemon

    %% Click Events
    click ChronyDaemon "https://github.com/mlichvar/chrony/blob/master/main.c"
    click ChronyClient "https://github.com/mlichvar/chrony/blob/master/client.c"
    click CMD "https://github.com/mlichvar/chrony/blob/master/cmdparse.c"
    click Config "https://github.com/mlichvar/chrony/blob/master/conf.c"
    click Logging "https://github.com/mlichvar/chrony/blob/master/logging.c"
    click NetIO "https://github.com/mlichvar/chrony/blob/master/ntp_io.c"
    click Prot "https://github.com/mlichvar/chrony/blob/master/ntp_core.c"
    click Sec "https://github.com/mlichvar/chrony/blob/master/nts_ke_client.c"
    click TDCore "https://github.com/mlichvar/chrony/blob/master/samplefilt.c"
    click Ref "https://github.com/mlichvar/chrony/blob/master/refclock.c"
    click OS "https://github.com/mlichvar/chrony/blob/master/hwclock.c"
    click Persist "https://github.com/mlichvar/chrony/blob/master/leapdb.c"

    %% Styles
    classDef service fill:#FFD700,stroke:#DAA520
    classDef config fill:#ADD8E6,stroke:#1E90FF
    classDef logging fill:#90EE90,stroke:#32CD32
    classDef net fill:#FFA07A,stroke:#FF4500
    classDef core fill:#DDA0DD,stroke:#BA55D3
    classDef security fill:#FFC0CB,stroke:#FF1493
    classDef driver fill:#D3D3D3,stroke:#696969
    classDef storage fill:#87CEEB,stroke:#4682B4
    classDef external fill:#F5F5F5,stroke:#A9A9A9,stroke-dasharray:5 5
```
