# nateageek/syncreeper architecture

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

- Interactive diagram: https://gitdiagram.com/nateageek/syncreeper
- Repository: https://github.com/nateageek/syncreeper

## Overview

1. **This is a monorepo with two main planes: control and runtime.**  
   The control plane is the user-facing CLI, setup flow, and terminal dashboard. The runtime plane is the Pulumi-managed host configuration plus the sync daemon, Syncthing, and optional reverse SSH tunnel. The repo is organized so the control plane configures the runtime plane rather than replacing it.

2. **`packages/host` is the core infrastructure package.**  
   It contains the Pulumi program that provisions a hardened host in phases, with explicit modules for user and directory creation plus service installation/configuration. The `services/` tree is the main architecture boundary: each subsystem is isolated into its own module, and most have Linux/macOS variants under `darwin.ts` and `linux.ts`.

3. **The host deployment pipeline is layered by responsibility.**  
   The modules indicate a sequence of setup: system packages, firewall, SSH hardening, SSHGuard, auto-updates, GitHub sync, Syncthing, and optional passthrough. This is the primary “infrastructure diagram” axis: base OS hardening first, then repository sync, then peer sync and tunnel features.

4. **`packages/sync` is the repository mirroring engine.**  
   This standalone app handles GitHub repository enumeration and local checkout/update behavior. Its internal boundaries are GitHub API access, git operations, locking, and `.stignore` generation. The runtime data flow is: GitHub REST API → repository list → local clone/fetch/reset in the repos directory.

5. **Repository sync is intentionally incremental and guarded.**  
   The README and sync package structure show that the sync process avoids concurrent runs via a lock file, skips dirty repositories, and uses shallow clone plus fetch/reset for updates. That makes the sync engine a stateful local worker rather than a stateless API client.

6. **Syncthing is the distribution layer between devices.**  
   The host package’s Syncthing service module configures the shared folder and device trust model, while the CLI exposes device-management actions. In the overall system, the host sync directory is the source of truth, and Syncthing propagates it to laptops, desktops, and NAS devices peer-to-peer.

7. **Security is a first-class subsystem, not an add-on.**  
   The host package separates firewall, SSH hardening, SSHGuard, and auto-updates into distinct modules. The README shows the intent: default-deny inbound rules, key-only SSH, brute-force protection, unattended upgrades, and systemd sandboxing. These are part of the deployment architecture and should be drawn as protective layers around the host runtime.

8. **Reverse SSH tunneling is modeled as an optional subsystem.**  
   The `passthrough` service in `packages/host` configures the server side, and `packages/node-passthrough` provides the client-side command set (`setup`, `start`, `stop`, `status`, `uninstall`). Architecturally, this is a separate path from the sync flow: it exists to reach a home machine behind NAT through the VPS.

9. **The CLI is a thin orchestration layer over host operations.**  
   `packages/cli` exposes user commands like dashboard, setup, sync-now, get-device-id, add-device, and redeploy. It appears to delegate real system changes to shared host utilities and Pulumi-aware routines, so it should be drawn as a front-end to administration actions, not as the system’s execution core.

10. **The TUI is a live monitoring and action surface.**  
   `packages/tui` is a React/Ink terminal app with tabs for Overview, GitHub Sync, Syncthing, Passthrough, and Security. It polls service status, streams logs, and can issue start/stop/restart actions. In a diagram, it sits above the runtime as an operator console that reads system state and triggers service actions.

11. **`packages/shared` provides cross-package platform abstractions.**  
   This package holds platform detection and shared types used by both CLI and host code. Its presence reflects a core architectural constraint: many behaviors are OS-specific, so common contracts are isolated from platform implementations.

12. **Platform branching is central to the design.**  
   The repo explicitly supports Linux and macOS, with separate config, command, resource, and service implementations in `packages/host`. That means the architecture diagram should show a shared service interface layer feeding distinct OS backends, especially for firewall, SSH, Syncthing, package installation, and auto-update behavior.

13. **External dependencies shape the system boundaries.**  
   GitHub is the source of repository metadata and code; Syncthing is the peer sync fabric; Pulumi is the deployment engine; systemd/launchd and UFW/pf provide host integration; SSH/SSHGuard provide access and abuse control. These are not incidental libraries—they define the main runtime and infrastructure boundaries.

14. **A useful diagram mental model is: one config source, two execution planes.**  
   Configuration enters through Pulumi and the CLI, then fans out into host provisioning and service runtime. At runtime, the sync service writes to the repos directory, Syncthing mirrors that directory to trusted devices, the TUI observes and controls services, and the passthrough path optionally exposes a separate SSH tunnel service.

Main entry points: [`packages/host/src/services`](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services) (Services), [`packages/host/src`](https://github.com/nateageek/syncreeper/tree/main/packages/host/src) (Host), [`packages/tui/src`](https://github.com/nateageek/syncreeper/tree/main/packages/tui/src) (TUI), [`packages/sync/src`](https://github.com/nateageek/syncreeper/tree/main/packages/sync/src) (Sync engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_control["Control plane"]
  node_node_cli["CLI<br/>orchestration"]
  node_node_tui["TUI<br/>operator console"]
  node_node_node_passthrough["Passthrough CLI<br/>tunnel client"]
end

subgraph group_group_runtime["Runtime plane"]
  node_node_host[("Host<br/>pulumi program")]
  node_node_host_config["Config<br/>paths and types"]
  node_node_host_resources["Resources<br/>user and dirs"]
  node_node_host_services["Services<br/>service modules"]
  node_node_fw{{"Firewall<br/>security service"}}
  node_node_ssh{{"SSH<br/>access hardening"}}
  node_node_sshguard{{"SSHGuard<br/>abuse protection"}}
  node_node_updates{{"Auto-updates<br/>maintenance service"}}
  node_node_github_sync{{"GitHub Sync<br/>mirror service"}}
  node_node_syncthing{{"Syncthing<br/>peer sync"}}
  node_node_passthrough{{"Passthrough<br/>optional tunnel"}}
  node_node_sync[("Sync engine<br/>local worker")]
end

subgraph group_group_shared["Shared core"]
  node_node_shared["Shared<br/>platform core"]
end

subgraph group_group_external["External systems"]
  node_node_github(("GitHub<br/>api source"))
  node_node_syncthing_ext(("Syncthing network<br/>peer fabric"))
  node_node_pulumi(("Pulumi<br/>deployment engine<br/>[Pulumi.yaml]"))
  node_node_os(("OS services<br/>host integration"))
end

node_node_cli -->|"setup / redeploy"| node_node_host
node_node_cli -->|"sync-now"| node_node_sync
node_node_cli -->|"dashboard"| node_node_tui
node_node_cli -->|"tunnel actions"| node_node_node_passthrough
node_node_tui -->|"observe sync"| node_node_sync
node_node_tui -->|"observe peer sync"| node_node_syncthing
node_node_tui -->|"observe tunnel"| node_node_passthrough
node_node_tui -->|"security view"| node_node_fw
node_node_node_passthrough -->|"configure client"| node_node_passthrough
node_node_host -->|"uses"| node_node_host_config
node_node_host -->|"provisions"| node_node_host_resources
node_node_host -->|"installs services"| node_node_host_services
node_node_host -->|"runs on"| node_node_pulumi
node_node_host -->|"integrates with"| node_node_os
node_node_host_services -->|"includes"| node_node_fw
node_node_host_services -->|"includes"| node_node_ssh
node_node_host_services -->|"includes"| node_node_sshguard
node_node_host_services -->|"includes"| node_node_updates
node_node_host_services -->|"includes"| node_node_github_sync
node_node_host_services -->|"includes"| node_node_syncthing
node_node_host_services -->|"includes"| node_node_passthrough
node_node_github_sync -->|"coordinates"| node_node_sync
node_node_sync -->|"reads metadata"| node_node_github
node_node_sync -->|"uses types"| node_node_shared
node_node_syncthing -->|"replicates to"| node_node_syncthing_ext
node_node_host -->|"uses types"| node_node_shared
node_node_tui -->|"uses types"| node_node_shared

click node_node_cli "https://github.com/nateageek/syncreeper/tree/main/packages/cli/src"
click node_node_tui "https://github.com/nateageek/syncreeper/tree/main/packages/tui/src"
click node_node_node_passthrough "https://github.com/nateageek/syncreeper/tree/main/packages/node-passthrough/src"
click node_node_host "https://github.com/nateageek/syncreeper/tree/main/packages/host/src"
click node_node_host_config "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/config"
click node_node_host_resources "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/resources"
click node_node_host_services "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services"
click node_node_fw "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/firewall"
click node_node_ssh "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/ssh"
click node_node_sshguard "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/sshguard"
click node_node_updates "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/auto-updates"
click node_node_github_sync "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/github-sync"
click node_node_syncthing "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/syncthing"
click node_node_passthrough "https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/passthrough"
click node_node_shared "https://github.com/nateageek/syncreeper/tree/main/packages/shared/src"
click node_node_sync "https://github.com/nateageek/syncreeper/tree/main/packages/sync/src"
click node_node_pulumi "https://github.com/nateageek/syncreeper/blob/main/Pulumi.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_tui,node_node_node_passthrough toneBlue
class node_node_host,node_node_host_config,node_node_host_resources,node_node_host_services,node_node_fw,node_node_ssh,node_node_sshguard,node_node_updates,node_node_github_sync,node_node_syncthing,node_node_passthrough,node_node_sync toneAmber
class node_node_shared toneMint
class node_node_github,node_node_syncthing_ext,node_node_pulumi,node_node_os toneRose
```

## Components

### Control plane

User-facing orchestration and operator interfaces.

- [CLI](https://github.com/nateageek/syncreeper/tree/main/packages/cli/src): orchestration · Thin command layer for setup, sync, device management, and redeploy actions. · `packages/cli/src`
- [TUI](https://github.com/nateageek/syncreeper/tree/main/packages/tui/src): operator console · Ink-based terminal dashboard for observing services and issuing actions. · `packages/tui/src`
- [Passthrough CLI](https://github.com/nateageek/syncreeper/tree/main/packages/node-passthrough/src): tunnel client · Client-side commands for configuring and managing reverse SSH tunnel behavior. · `packages/node-passthrough/src`

### Runtime plane

Pulumi-managed host provisioning and long-running services.

- [Host](https://github.com/nateageek/syncreeper/tree/main/packages/host/src): pulumi program · Core infrastructure package that provisions the hardened host and configures services. · `packages/host/src`
- [Config](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/config): paths and types · Shared host configuration, path resolution, and platform-specific constants. · `packages/host/src/config`
- [Resources](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/resources): user and dirs · User and directory provisioning used during host setup. · `packages/host/src/resources`
- [Services](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services): service modules · Main architecture boundary for host services and OS-specific implementations. · `packages/host/src/services`
- [Firewall](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/firewall): security service · Default-deny inbound rules and host firewall configuration. · `packages/host/src/services/firewall`
- [SSH](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/ssh): access hardening · SSH configuration and hardening for key-only remote access. · `packages/host/src/services/ssh`
- [SSHGuard](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/sshguard): abuse protection · Brute-force protection and ban management for SSH access. · `packages/host/src/services/sshguard`
- [Auto-updates](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/auto-updates): maintenance service · Unattended update configuration and service integration. · `packages/host/src/services/auto-updates`
- [GitHub Sync](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/github-sync): mirror service · Host-side repository sync service that pulls code into the local repos directory. · `packages/host/src/services/github-sync`
- [Syncthing](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/syncthing): peer sync · Shared-folder replication and device trust configuration. · `packages/host/src/services/syncthing`
- [Passthrough](https://github.com/nateageek/syncreeper/tree/main/packages/host/src/services/passthrough): optional tunnel · Server-side reverse SSH tunnel support for reaching a host behind NAT. · `packages/host/src/services/passthrough`
- [Sync engine](https://github.com/nateageek/syncreeper/tree/main/packages/sync/src): local worker · Standalone repository mirroring engine with GitHub access, git operations, locking, and stignore generation. · `packages/sync/src`

### Shared core

Cross-package abstractions and common types.

- [Shared](https://github.com/nateageek/syncreeper/tree/main/packages/shared/src): platform core · Cross-package platform detection and common types. · `packages/shared/src`

### External systems

Outside services and host integrations that define system boundaries.

- **GitHub**: api source · Source of repository metadata and code for mirroring and deployment.
- **Syncthing network**: peer fabric · Device-to-device replication layer for propagating the repos directory.
- [Pulumi](https://github.com/nateageek/syncreeper/blob/main/Pulumi.yaml): deployment engine · Infrastructure orchestration engine for host provisioning. · `Pulumi.yaml`
- **OS services**: host integration · Linux/macOS service managers, firewall tooling, and package management backends.

## Connections

- CLI → Host: setup / redeploy · CLI triggers host provisioning and deployment routines.
- CLI → Sync engine: sync-now · CLI invokes local repository mirroring actions.
- CLI → TUI: dashboard · CLI exposes the operator dashboard entrypoint.
- CLI → Passthrough CLI: tunnel actions · CLI delegates tunnel setup and lifecycle commands.
- TUI → Sync engine: observe sync · Dashboard reads sync status and logs.
- TUI → Syncthing: observe peer sync · Dashboard monitors Syncthing health and actions.
- TUI → Passthrough: observe tunnel · Dashboard shows passthrough status and controls.
- TUI → Firewall: security view · Dashboard surfaces security-related host state.
- Passthrough CLI → Passthrough: configure client · Client commands manage the local side of reverse SSH tunneling.
- Host → Config: uses · Pulumi program consumes paths and configuration definitions.
- Host → Resources: provisions · Host setup creates users and directories before services.
- Host → Services: installs services · Host program wires the service modules into the deployment.
- Host → Pulumi: runs on · Infrastructure is expressed as a Pulumi program.
- Host → OS services: integrates with · Host modules target platform service managers and system tools.
- Services → Firewall: includes · Service boundary contains firewall hardening.
- Services → SSH: includes · Service boundary contains SSH hardening.
- Services → SSHGuard: includes · Service boundary contains brute-force protection.
- Services → Auto-updates: includes · Service boundary contains unattended update setup.
- Services → GitHub Sync: includes · Service boundary contains repository sync service.
- Services → Syncthing: includes · Service boundary contains peer sync configuration.
- Services → Passthrough: includes · Service boundary contains optional reverse tunnel support.
- GitHub Sync → Sync engine: coordinates · Host service relies on the sync engine for repository mirroring behavior.
- Sync engine → GitHub: reads metadata · Sync engine enumerates repositories from GitHub.
- Sync engine → Shared: uses types · Sync engine shares platform and common types.
- Syncthing → Syncthing network: replicates to · Host-side configuration connects the local folder to peer devices.
- Host → Shared: uses types · Host code relies on shared platform abstractions.
- TUI → Shared: uses types · UI shares platform-aware command and status types.
