internet_use_control/docs/outline/03-code-map.md

Internet Use Control — Code Map

Target: AI agents. Writing style: ASD-STE100 Simplified Technical English.

Module

gitea.lab.audasmedia.com.au/sam/internet_use_control, Go 1.25. The image is CGO-free. SQLite is the pure-Go modernc.org/sqlite driver.

Folder Tree

cmd/control/main.go          entry point and subcommands
internal/config/             environment configuration and validation
internal/auth/               signed-cookie session login and CSRF
internal/store/              SQLite: open, migrations, queries
  store.go                   connection, migration runner, maintenance loop
  devices.go                 device registry and desired state
  schedules.go               weekly windows and the effective state
  lists.go                   block and allow lists
  reports.go                 presence, telemetry, the daily rollup
  overrides.go               override history and the device keycode
  alerts.go                  alert records and per-device dedup state
  migrations/001_init.sql … 005_alerts.sql
internal/mqtt/
  link.go                    paho client, subscriptions, publish, TLS
  payload.go                 the topic and payload contract for the clients
internal/alert/alert.go      the limit and offline alert engine
internal/apprise/apprise.go  the Apprise API client
internal/hub/                the Hub contract: capabilities, answers, notify
internal/web/
  server.go                  routes, middleware, session
  devices.go                 the device registry and manual lock/unlock
  schedules.go               the weekly schedule and list editors
  usage.go                   the usage screen
  admin_api.go               the versioned admin API and the keycode endpoint
  hub_api.go                 /capabilities, /ask, /notify
  templates/                 login, dashboard, editors, usage, partials
  static/                    tokens.css, app.css, theme.js, htmx, fonts
android/                     the kids' Android client (Gradle, Kotlin)
  app/src/main/java/au/audasmedia/webrestrict/kids/
    KidsApp.kt               application class
    MainActivity.kt          the kid's status screen
    BlockAccessibilityService.kt   foreground app detection
    OverlayController.kt     the full-screen block overlay
    BlockEngine.kt           the block decision
    DeviceConfig.kt          the config payload model
    MqttController.kt        the broker link
    TamperReporter.kt        the FR-17 tamper report
    UsageCollector.kt        Usage Access telemetry
    TelemetryReporter.kt     telemetry publish
    SiteFilterVpnService.kt  the device-local VpnService
    SiteFilter.kt            the site decision
    DnsMessage.kt            DNS parsing
    IpPacket.kt              IP packet parsing
    AppPrefs.kt              the cached config on disk
    BootReceiver.kt          start after boot
    TelemetryStore.kt        local telemetry buffer
  tools/emu-proof.sh         headless emulator proof
deploy/caddy/                the vhost on .35
deploy/mosquitto/            the TLS listener, the accounts, the ACL, the verifier
deploy/verify-phase8.sh      the lock latency proof
deploy/verify-phase9.sh      the Hub and alert proof
docs/                        this documentation set

Entry Point

cmd/control/main.go starts the web server. It also holds the subcommands:

Subcommand	Purpose
hash-password	Make a bcrypt hash for a password.
mqtt-clients	Print the MQTT identity of every device.
rollup	Rebuild the daily telemetry rollup.
keycode	Set or generate the shared device keycode.
alerts	Print recent alerts.
usage	Print usage from the database.

Dependencies

Module	Use
github.com/eclipse/paho.mqtt.golang	The MQTT client.
modernc.org/sqlite	The pure-Go SQLite driver. No CGO.
golang.org/x/crypto	bcrypt for the password and the keycode hashes.

The web layer uses the Go standard library only. The UI uses HTMX 2.0.4, vendored under internal/web/static/.

Database Migrations

File	Change
001_init.sql	Devices, schedules, lists, state, telemetry, overrides, audit.
002_telemetry_unique.sql	One telemetry row per (device, day, app, domain).
003_usage_rollup.sql	The daily rollup table.
004_overrides_grant.sql	The grant column and the override history.
005_alerts.sql	The alerts table and the dedup state.

Migrations apply in order at start-up. Never hard-delete a device or its history (AGENTS.md section 10, rule 10).

Android Client

The client is a normal Gradle project with its own gradlew. The block path is the Accessibility Service plus the overlay. The site path is the local VpnService. The tamper path is TamperReporter.kt. The client keeps the last config in AppPrefs.kt. There is no Device Owner and no managed profile.

Known Gaps in the Code

• Phase 4, the Windows computer client, does not exist. No Python client and no process blocking are in the tree.
• The MQTT cmd and ack topics are design only. No code uses them.
• The phone client reports telemetry from Usage Access. Site filtering uses the local VpnService.