# zerotier/zerotierone architecture

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

- Interactive diagram: https://gitdiagram.com/zerotier/zerotierone
- Repository: https://github.com/zerotier/zerotierone

## Overview

Based on our analysis of the ZeroTier source and README, you are dealing with a highly modular (and cross‑platform) distributed virtual networking system. The repository contains separate directories for the core virtual switch (“node”), the integrated service layer (“service”), a network controller (“controller”), the operating system–dependent integration layer (“osdep”), and even support for Java–based JNI wrappers (in “java”) along with Windows-specific UI (in “windows”) and packaging (in “pkg”). In addition, there is a rich “ext” folder that houses many third–party libraries plus extra components (like Prometheus metrics, rule compilers, and support for multiple architectures). The README makes it clear that ZeroTier implements two major virtual layers: a secure peer-to-peer network layer (VL1) and an Ethernet emulation layer (VL2) with SDN features.

##### Main Components
- Core Virtual Ethernet Switch (node):
– This is the heart of the data plane; it implements network packet processing, encryption/decryption, tunneling, switching and virtual routing.
– It is designed to be embeddable and platform‐independent (notice the non‑usage of C++11 features to allow embedded builds).
- Network Controller (controller):
– Acts much like an SDN controller managing membership, configuration, and other control functions (e.g., assigning network IDs, controlling access rules).
– It works closely with the service layer and supplies the “control plane” for ZeroTier.
- Service and API Layer (service):
– Wraps the core node and provides interfaces (JSON API) for configuration, joining/leaving networks, and running the node as a daemon.
– Offers administrative access (via CLI, API, and Prometheus metrics endpoints).
- OS Dependent Layer (osdep):
– Contains the libraries and drivers required to interface with native networking (e.g., creating tap devices on Linux, Windows Ethernet tap drivers, macOS helpers).
- External Interfaces and Clients:
– Command-line “zerotier-cli” tool, the Java JNI wrapper (for mobile/Android platforms), and Windows UI components.
– Also include the Prometheus Metrics endpoint and the HTTP / App server for hosting single page apps.
- Packaging/Deployment Components:
– The “pkg” directory (with subfolders for various platforms like Synology, QNAP, Snap, etc.) indicates that installers and deployment scripts are built around the core components.

- The node should be shown communicating with the controller (control messages) so that configuration changes and network membership decisions are exchanged.
- The OS dep layer must be depicted as a supporting “infrastructure adapter” that the node/service uses to create virtual network interfaces and handle OS-specific events.
- External API paths (e.g., the JSON API on port 9993, Prometheus Metrics endpoint) that allow administrators or external clients (CLI, web UI, mobile app) to configure or query the system.

##### Architectural Patterns and Design Principles
- The architecture is layered: a clear separation between the core virtual switch, the higher-level service control and configuration, and the OS integration.
- There is a micro‑service–like decomposition internally: the control plane (controller) is decoupled from the data plane (node), and deployment is further aided by “ext” and “pkg” support.
- Peer-to-peer communications (VL1) and Ethernet virtualization (VL2) are the underlying design idioms.
- Security is built in (end-to-end encryption, secret keys, access tokens for API/metrics).
- Cross-platform portability and modularity are evident – even a rule compiler written in JavaScript is segregated from the main functionality.

##### Relevant Technologies and Frameworks
- C/C++ are predominant in the core system.
- For OS integration, platform-specific libraries are used (e.g., Windows driver code, macOS network tap wrappers).
- Prometheus client libraries are embedded to expose metrics.
- The use of JSON for API control and integration (see local.conf configuration and CLI command interactions).
- In addition, packaging builds (CMake, Makefiles, Visual Studio solutions) are used; the “ext” folder shows third–party native libraries for crypto, networking protocols, etc.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "External Interfaces"
        CLI["CLI Tool"]:::presentation
        WebUI["HTTP Server/Web UI"]:::presentation
        Metrics["Prometheus Metrics Endpoint"]:::presentation
        JNI["Java JNI Wrapper"]:::presentation
        WinUI["Windows UI"]:::presentation
    end

    subgraph "Service/API Layer"
        Service["Service and API Layer"]:::service
    end

    subgraph "Core Networking Engine"
        Node["Core Virtual Ethernet Switch"]:::core
    end

    subgraph "Control Plane"
        Controller["Network Controller"]:::controller
    end

    subgraph "OS Integration"
        OSDep["OS Dependent Layer"]:::osdep
    end

    subgraph "Packaging/Deployment"
        Packaging["Packaging & Deployment"]:::packaging
    end

    %% External Interfaces to Service/API Layer
    CLI -->|"JSONAPI"| Service
    WebUI -->|"HTTPAPI"| Service
    Metrics -->|"MetricsQuery"| Service
    JNI -->|"JNICalls"| Service
    WinUI -->|"UICommands"| Service

    %% Service interactions with Core and Control Plane
    Service -->|"ControlCommand"| Node
    Service -->|"ConfigChanges"| Controller

    %% Core Networking Engine and Control Plane communication
    Node <-->|"ControlMessages"| Controller

    %% OS Integration supports Core Networking Engine
    OSDep -->|"OS_NetworkI/O"| Node

    %% Packaging deploys the Service/API Layer
    Packaging -->|"Deploys"| Service

    %% Click Events:
    click Node "https://github.com/zerotier/zerotierone/tree/dev/node/"
    click Controller "https://github.com/zerotier/zerotierone/tree/dev/controller/"
    click Service "https://github.com/zerotier/zerotierone/tree/dev/service/"
    click OSDep "https://github.com/zerotier/zerotierone/tree/dev/osdep/"
    click JNI "https://github.com/zerotier/zerotierone/tree/dev/java/"
    click WinUI "https://github.com/zerotier/zerotierone/tree/dev/windows/"
    click Packaging "https://github.com/zerotier/zerotierone/tree/dev/pkg/"

    %% Class Definitions for styling
    classDef presentation fill:#f9c74f,stroke:#000,stroke-width:1px
    classDef service fill:#90be6d,stroke:#000,stroke-width:1px
    classDef core fill:#577590,stroke:#000,stroke-width:1px,color:#fff
    classDef controller fill:#f94144,stroke:#000,stroke-width:1px,color:#fff
    classDef osdep fill:#277da1,stroke:#000,stroke-width:1px,color:#fff
    classDef packaging fill:#f3722c,stroke:#000,stroke-width:1px,color:#fff
```
