# singlestore-labs/tailscale-manager architecture

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

- Interactive diagram: https://gitdiagram.com/singlestore-labs/tailscale-manager
- Repository: https://github.com/singlestore-labs/tailscale-manager

## Overview

##### Overall System Components
- Core Application: This is the main Haskell executable (found under app/Main.hs and src/TailscaleManager.hs) that initializes the application, loads the configuration file (JSON/YAML), and orchestrates the discovery and updating of routes.
- Discovery Modules: Represent the individual discovery strategies that the application supports. These include:
- Static Routes (provided via the “routes” list)
- DNS based hostRoutes (provided via the “hostRoutes” list)
- AWS Managed Prefix Lists (provided via the “awsManagedPrefixLists” list)
As separate modules (e.g., src/TailscaleManager/Discovery/AWSManagedPrefixList.hs, src/TailscaleManager/Discovery/DNS.hs) to show how each discovery method plugs into the main system.
- Configuration and Logging: Capture the fact that the application includes dedicated configuration parsing (likely the Config.hs module) and logging facilities (found in TailscaleManager/Logging.hs). They are critical for proper operation and debugging.
- Tailscale Interaction: This is the interface to the Tailscale daemon. The application calls the “tailscale” command (or otherwise communicates with the tailscaled socket) to advertise new routes. Show this as an external dependency that connects to the host’s Tailscale system.
- Command-Line Interface: Represent the CLI layer that accepts runtime parameters (for example, flags like --dryrun, --tailscale, --interval) to adjust the behavior of the application.

##### Relationships and Data Flow
- The valid configuration is then passed to the Discovery Engine, where each discovery module (static routes, DNS lookups, AWS Managed Prefix Lists) processes its particular information.
- The results from these discovery modules are aggregated and fed into the application’s decision logic.
- Then, this processed route information is supplied to the Tailscale Interaction component, which communicates over a socket or calls the Tailscale binary to update the advertised routes accordingly.
- Optionally, include error and logging flows going to the Logging component so that operational issues and debug information are centrally captured.

##### Architectural Patterns and Technologies
- Modular design: Each discovery method is implemented as a separate module and can be extended to support future discovery methods.
- CLI & configuration driven: The system is configured via external files (JSON/YAML) and runtime command-line parameters.
- Integration with external systems: There is an explicit dependency on the Tailscale daemon and external services (DNS servers and AWS APIs).
- Deployment flexibility: Emphasize the Docker and Nix/NixOS integration points presented in the README. For Docker, include a component representing the containerized runtime that bundles both tailscale-manager and the Tailscale binary. For NixOS, highlight the Nix flake and module that transforms the service into a systemd-managed service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal System
    subgraph "Internal System"
        ConfigLoader["Configuration Loader"]:::internal
        CLIFront["CLI Frontend"]:::internal
        CoreLogic["Core Logic"]:::internal
        Scheduler["Scheduler Loop"]:::internal
        DiscoveryAgg["Discovery Aggregator"]:::internal
        StaticRoutes["Static Routes Discovery"]:::internal
        DNSDisc["DNS Discovery"]:::internal
        AWSDisc["AWS Managed Prefix Lists Discovery"]:::internal
        TailscaleClient["Tailscale Client Interface"]:::internal
        Logging["Logging"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        TailscaleDaemon["Tailscale Daemon"]:::external
    end

    %% Deployment Options
    subgraph "Deployment Options"
        subgraph "Docker Container"
            Dockerfile["Dockerfile"]:::deployment
            DockerIgnore[".dockerignore"]:::deployment
        end
        subgraph "NixOS Module"
            Flake["flake.nix"]:::deployment
            NixModule["nix/nixos-module.nix"]:::deployment
            FlakeLock["flake.lock"]:::deployment
        end
    end

    %% Data Flow - Initialization and Scheduling
    Scheduler -->|"triggers"| CoreLogic
    CLIFront -->|"initializes"| CoreLogic
    ConfigLoader -->|"loads_config"| CoreLogic
    CoreLogic -->|"starts_discovery"| DiscoveryAgg

    %% Discovery Flow
    DiscoveryAgg -->|"invokes"| StaticRoutes
    DiscoveryAgg -->|"invokes"| DNSDisc
    DiscoveryAgg -->|"invokes"| AWSDisc
    StaticRoutes -->|"returns_routes"| DiscoveryAgg
    DNSDisc -->|"returns_routes"| DiscoveryAgg
    AWSDisc -->|"returns_routes"| DiscoveryAgg

    %% Route Announcement and Logging
    DiscoveryAgg -->|"aggregated_routes"| TailscaleClient
    TailscaleClient -->|"updates_routes"| TailscaleDaemon
    CoreLogic -->|"logs_events"| Logging

    %% Deployment Packaging
    CoreLogic -->|"packaged_as_container"| Dockerfile
    CoreLogic -->|"packaged_as_service"| Flake

    %% Click Events
    click CLIFront "https://github.com/singlestore-labs/tailscale-manager/blob/main/app/Main.hs"
    click CoreLogic "https://github.com/singlestore-labs/tailscale-manager/blob/main/src/TailscaleManager.hs"
    click ConfigLoader "https://github.com/singlestore-labs/tailscale-manager/blob/main/src/TailscaleManager/Config.hs"
    click Logging "https://github.com/singlestore-labs/tailscale-manager/blob/main/src/TailscaleManager/Logging.hs"
    click DNSDisc "https://github.com/singlestore-labs/tailscale-manager/blob/main/src/TailscaleManager/Discovery/DNS.hs"
    click AWSDisc "https://github.com/singlestore-labs/tailscale-manager/blob/main/src/TailscaleManager/Discovery/AWSManagedPrefixList.hs"
    click Dockerfile "https://github.com/singlestore-labs/tailscale-manager/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/singlestore-labs/tailscale-manager/blob/main/.dockerignore"
    click Flake "https://github.com/singlestore-labs/tailscale-manager/blob/main/flake.nix"
    click NixModule "https://github.com/singlestore-labs/tailscale-manager/blob/main/nix/nixos-module.nix"
    click FlakeLock "https://github.com/singlestore-labs/tailscale-manager/blob/main/flake.lock"

    %% Styles
    classDef internal fill:#AEE3F9,stroke:#333,stroke-width:2px;
    classDef external fill:#C0F9A6,stroke:#333,stroke-width:2px;
    classDef deployment fill:#F9E79F,stroke:#333,stroke-width:2px;
```
