How it fits together

Everything hangs off one idea: the child’s devices always reach the internet through a WireGuard VPN to the home router, a Firewalla. The Firewalla can then filter and log their web traffic wherever they are. Browser history fills in what the filter can’t see. The parents’ apps read both.

 Child's devices                     Firewalla (home)                       Parents
 ───────────────                     ────────────────                       ───────
 iPhone, iPad ── WireGuard ──┐
                             ├──▶  URL filter (mitmproxy)  ──▶ internet
 Mac ─────────── WireGuard ──┘       ├ blocks by rule and Focus Mode
   │                                 ├ logs page loads
   │                                 └ API :8091 ◀──────────────┬── Family Filter for Mac
   │                                                            │
   └ History Sync ── every 15 min ─▶ History service :8092 ◀────┤
     (Safari + Chrome history)                                  │
                                     Notifier :8093 ── APNs ───▶└── Family Filter for iPhone

On the child’s devices

• An always-on VPN. Each device has a WireGuard tunnel to the Firewalla, set to connect on demand on every network. The filter only sees a device while its tunnel is up, so a lot of the project is about noticing when it isn’t (see Alerts).
• The filter’s certificate. The filter decrypts HTTPS so it can see full URLs and block a single page, not just a whole site. Each device trusts the filter’s own certificate authority, installed as a configuration profile.
• History Sync (the Mac only) reads Safari’s and Chrome’s history files every 15 minutes and sends new visits on. That catches browsing the filter missed: with the VPN off, or in apps it can’t decrypt. Visits synced to the Mac from the child’s iPhone and iPad through iCloud come along too.
• Locks. Configuration profiles stop the child turning these off from a standard account: the History Sync Lock, the Chrome History Lock and the VPN profile itself.

On the Firewalla

Three small services, each in its own container:

Service	Port	What it does
URL filter	8091 (API)	mitmproxy in transparent mode, with an add-on that applies rules and Focus Mode, logs page loads and answers the parents’ apps
History service	8092	Keeps History Sync’s files, append-only, for 90 days, and until an archive Mac holds them
Notifier	8093	Watches the filter and pushes what needs a parent to their iPhones

A watchdog script keeps the firewall rules in place, checks that the filter is answering, and records which tunnels carry traffic.

The parents’ apps reach these services over Tailscale, at real HTTPS addresses that work at home and away. Nothing on the Firewalla is opened to the internet. See Away from home.

For the parents

• Family Filter for Mac on a Mac: the history as charts, categories and a timeline, the filter’s rules, Focus Mode and the off switches.
• Family Filter for iPhone on an iPhone: alerts as push notifications, the off switches, Focus, and the last two weeks of history.

Where history lives

History Sync writes the same CSV files to two places:

1. The history service on the Firewalla, which the child can’t read, edit or delete. This is becoming the main copy (design note).
2. A shared iCloud Drive folder, the original route, kept as a second copy during the changeover.

The files are one per computer per day. Their columns are in CSV format.