# 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`.