How mahm0udnasr/sadd works
sadd is a Linux website blocker whose source of truth is a managed section of /etc/hosts. Users block or unblock normalized domains through CLI commands or the interactive TUI; timed blocks are removed by expire, while checks ask the system resolver whether blocking works. The graph preserves the documented group, blocklist, backup/restore, and read-only TUI capabilities. Some internal wiring is unsampled, so uncertain links are omitted rather than inferred.
Main entry points: hosts.go Hosts file state · cmd/tui.go TUI launcher · tui/tui.go Interactive app · block.go Block sites
Components 24
Entry points
- sadd binary
main.go - Command router
cmd/root.go
Blocking features
- Block sites
cmd/block.go - Unblock sites
cmd/unblock.go - List blocks
cmd/list.go - Built-in groups
internal/groups/groups.go - Groups command
cmd/groups.go - Blocklist controls
cmd/blocklist.go - List download and parsing
internal/blocklist/blocklist.go - Blocking check
cmd/check.go
Hosts state
- Hosts file state
internal/hosts/hosts.go - Safe file writes
internal/hosts/write.go - Atomic replacement
internal/hosts/atomic.go - Restore backup
cmd/restore.go
System services
- Expire timed blocks
cmd/expire.go - Systemd timers
internal/timer/timer.go - System DNS lookup
internal/dns/dns.go
Interactive interface
- TUI launcher
cmd/tui.go - Interactive app
internal/tui/tui.go - Action forms
internal/tui/forms.go - Screens and views
internal/tui/view.go
Other components
- User
- systemd
- System resolver
Connections 27
- User → sadd binary: runs
README.md - sadd binary → Command router: executes
main.go - Command router → TUI launcher: opens by default
cmd/root.go - Command router → Block sites: routes commands
cmd/root.go - Block sites → Hosts file state: updates
cmd/block.go - Block sites → Systemd timers: schedules expiry
cmd/block.go - Unblock sites → Hosts file state: removes entries
- List blocks → Hosts file state: reads entries
cmd/list.go - Groups command → Built-in groups: lists groups
cmd/groups.go - Blocklist controls → List download and parsing: downloads lists
cmd/blocklist.go - Blocklist controls → Hosts file state: reads and updates
cmd/blocklist.go - Blocking check → Hosts file state: reads blocked domains
cmd/check.go - Blocking check → System DNS lookup: checks resolution
cmd/check.go - Safe file writes → Atomic replacement: replaces safely
- Restore backup → Hosts file state: restores backup
cmd/restore.go - Expire timed blocks → Hosts file state: expires entries
cmd/expire.go - Expire timed blocks → Systemd timers: reschedules
cmd/expire.go - systemd → Expire timed blocks: runs at expiry
README.md - Systemd timers → systemd: creates timers
- TUI launcher → Interactive app: starts app
cmd/tui.go - TUI launcher → Block sites: reuses block logic
cmd/tui.go - TUI launcher → Blocklist controls: wires list actions
cmd/tui.go - Interactive app → Hosts file state: loads entries
internal/tui/tui.go - Interactive app → Action forms: handles form actions
internal/tui/tui.go - Interactive app → Screens and views: renders screens
internal/tui/view.go - User → Blocking check: checks a site
README.md - System resolver → System DNS lookup: answers lookup
README.md