# jauderho/nts-servers architecture

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

- Interactive diagram: https://gitdiagram.com/jauderho/nts-servers
- Repository: https://github.com/jauderho/nts-servers

## Overview

##### Project type and purpose
This is an open-source tooling project whose sole purpose is to maintain and generate a vetted list of NTP servers with NTS (Network Time Security) support. It ingests a YAML source file, runs small conversion/verification scripts, and outputs both a markdown README and a chrony configuration. It lives in a GitHub repo and relies on CI to enforce quality and connectivity.

##### Main components
a. Data source (nts-sources.yml) – a YAML file listing servers and metadata
b. Conversion & verification scripts
- ntpServerConverter.py: reads nts-sources.yml → rewrites README.md and chrony.conf
- ntsCheck.sh / verifyNTSServers.py: ping or test NTS connectivity against listed servers
- useCommitHash.sh: embeds commit hashes (for reproducibility)
c. Outputs
- README.md: generated list presented for users
- chrony.conf: config snippet for clients
d. CI/CD pipeline (GitHub Actions)
- Linting, security scans, connectivity checks, dependency reviews, spell checks
e. External dependencies
- Python runtime, shell
- GitHub (source control + Actions runner)
- Target NTS servers (for connectivity validation)

##### Relationships & data flow
- Developer edits nts-sources.yml → commit → GitHub Actions triggers
- ntpServerConverter.py reads nts-sources.yml → outputs updated README.md & chrony.conf
- Verification scripts hit each NTS server to confirm reachability/valid config
- CI jobs run linting & tests → on success, PR can be merged
- End users clone/download the repo or use chrony.conf directly

##### Architectural patterns & design principles
- Single responsibility: each script does one task (convert, check, tag)
- Data-driven generation: YAML is the single source of truth
- GitOps style: all changes flow through Git PRs and automated CI checks
- Minimal dependencies: relies only on Python stdlib, basic shell tools

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "GitHub Repository"
        direction TB
        YAML["nts-sources.yml"]:::data
        subgraph "scripts/"
            direction TB
            Converter["ntpServerConverter.py"]:::code
            VerifShell["ntsCheck.sh"]:::code
            VerifPy["verifyNTSServers.py"]:::code
            CommitHash["useCommitHash.sh"]:::code
        end
    end

    subgraph "GitHub Actions"
        direction TB
        WorkflowsDir[".github/workflows"]:::data
        Lint["Linting Workflow"]:::ci
        Semgrep["Static Analysis Workflow"]:::ci
        Spell["Spell Checking Workflow"]:::ci
        DepReview["Dependency Review Workflow"]:::ci
        Scorecard["Security Scanning Workflow"]:::ci
        RunConvert["run ntpServerConverter"]:::ci
        RunCheck["run ntsCheck"]:::ci
        CIIntegration["Dependabot Settings"]:::ci
    end

    subgraph "External NTS Servers"
        direction TB
        Server1["Server A"]:::external
        Server2["Server B"]:::external
        Server3["Server C"]:::external
    end

    EndUser["End User"]:::user

    YAML --> Converter
    Converter --> README["README.md"]:::data
    Converter --> Chrony["chrony.conf"]:::data

    YAML --> Lint
    Lint --> Semgrep
    Semgrep --> Spell
    Spell --> DepReview
    DepReview --> Scorecard
    Scorecard --> RunConvert
    Scorecard --> RunCheck

    RunConvert --> Converter
    RunCheck --> VerifShell
    RunCheck --> VerifPy

    VerifShell --> Server1
    VerifShell --> Server2
    VerifShell --> Server3
    VerifPy --> Server1
    VerifPy --> Server2
    VerifPy --> Server3

    README --> EndUser
    Chrony --> EndUser

    click YAML "https://github.com/jauderho/nts-servers/blob/main/nts-sources.yml"
    click Converter "https://github.com/jauderho/nts-servers/blob/main/scripts/ntpServerConverter.py"
    click VerifShell "https://github.com/jauderho/nts-servers/blob/main/scripts/ntsCheck.sh"
    click VerifPy "https://github.com/jauderho/nts-servers/blob/main/scripts/verifyNTSServers.py"
    click CommitHash "https://github.com/jauderho/nts-servers/blob/main/scripts/useCommitHash.sh"
    click README "https://github.com/jauderho/nts-servers/blob/main/README.md"
    click Chrony "https://github.com/jauderho/nts-servers/blob/main/chrony.conf"
    click WorkflowsDir "https://github.com/jauderho/nts-servers/tree/main/.github/workflows"
    click Lint "https://github.com/jauderho/nts-servers/blob/main/.github/workflows/linter.yml"
    click Semgrep "https://github.com/jauderho/nts-servers/blob/main/.github/workflows/semgrep.yml"
    click Spell "https://github.com/jauderho/nts-servers/blob/main/.github/workflows/codespell.yml"
    click DepReview "https://github.com/jauderho/nts-servers/blob/main/.github/workflows/dependency-review.yml"
    click Scorecard "https://github.com/jauderho/nts-servers/blob/main/.github/workflows/scorecard.yml"
    click CIIntegration "https://github.com/jauderho/nts-servers/blob/main/.github/dependabot.yml"

    classDef code fill:#d4fcdc,stroke:#2e8b57;
    classDef data fill:#cfeeff,stroke:#0366d6,shape:cylinder;
    classDef ci fill:#ffd8a8,stroke:#e67e00;
    classDef external fill:#e0e0e0,stroke:#999999;
    classDef user fill:#f9c2f2,stroke:#c71585;
```
