From 9a777b7e1e20fd99d53d7b0b6289f187df1f0a52 Mon Sep 17 00:00:00 2001
From: Henri Dohmen <henridohmen@posteo.com>
Date: Sat, 4 Apr 2026 15:19:21 +0200
Subject: [PATCH] Comments & Readme

---
 README.md                | 11 ++++++++++-
 host/roam/networking.nix |  3 ++-
 mod/nginx.nix            |  2 ++
 var/hosts.nix            |  2 ++
 4 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d363b48..ac08d8d 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,16 @@ Repository structure:
   Age-encrypted secrets managed and deployed via agenix.
 
 - **var/**
-  Shared constants and values used across the configuration.
+  Shared data used across the configuration. `hosts.nix` is the single source
+  of truth for per-host data (SSH keys, WireGuard config). Adding a new host
+  means adding an entry there and running `bin/gen-syncthing-cert`.
+
+## Network topology
+
+WireGuard overlay network (onet, 10.10.11.0/24). Roam is the
+hub and the only publicly reachable node; desktops peer with roam only.
+Roam also runs a Mullvad WireGuard tunnel used as an egress for the torrent
+container configured in table 1000.
 
 ## TODO
 
diff --git a/host/roam/networking.nix b/host/roam/networking.nix
index 483c161..6e4efec 100644
--- a/host/roam/networking.nix
+++ b/host/roam/networking.nix
@@ -1,3 +1,5 @@
+# Roam has two WireGuard interfaces: wg0 (onet hub) and mullvad. Outgoing
+# container traffic is routed through mullvad via routing table 1000.
 {
   var,
   config,
@@ -7,7 +9,6 @@
 let
   wireguard-port = 51820;
 in
-
 {
   age.secrets.mullvad-vpn-key = {
     file = secrets.roam."mullvad-vpn-key.age";
diff --git a/mod/nginx.nix b/mod/nginx.nix
index 75b6df6..bda13b9 100644
--- a/mod/nginx.nix
+++ b/mod/nginx.nix
@@ -1,3 +1,5 @@
+# Defines the `privateVirtualHosts` option: nginx vhosts served only on the
+# onet WireGuard interface using the internal TLS cert.
 {
   lib,
   options,
diff --git a/var/hosts.nix b/var/hosts.nix
index 28bc0ac..bc6c27c 100644
--- a/var/hosts.nix
+++ b/var/hosts.nix
@@ -1,3 +1,5 @@
+# Single source of truth for per-host data. Adding a host here (and running
+# bin/gen-syncthing-cert) wires it into all configs.
 {
   servers = {
     roam = {