Sam Rolfe
eb300b6701
Phase 10 (the last phase of this project) is the project-docs pass. Update the Gitea README, add the Mermaid source and rendered PNG, build the interactive Archify map, add the Vikunja board tasks, and write the Outline AI-context collection in Simplified Technical English. Deliverables: - README.md: status header, Phase 4 gap statement, "Architecture" section with embedded Mermaid + image + Archify link, "Documentation set" table, an explicit two-plane MQTT section (1883 plain+anonymous, 8883 TLS+ACLs), and the Android client's Usage Access and VpnService paths. - AGENTS.md section 11: tick Phase 10, leave Phase 4 unticked, status line now "9 of 10 done - only Phase 4 outstanding". - docs/architecture.mmd + docs/diagrams/architecture.png (mmdc). - docs/archify/architecture.architecture.json + docs/architecture-map.html (Archify, showcase, 9/9 checks, 0 errors). - docs/outline/00-index.md .. 04-agent-runbook.md (STE). - docs/vikunja-tasks.json (Vikunja project "Internet Use Control", id 20). - Obsidian note written to 010 inbox on .27; the obsidian-sorter proposed a folder and waits for the vault owner's approval. Phase 4 (Python Windows computer client) is deliberately deferred and is NOT built. Every document says so. Co-Authored-By: Paperclip <noreply@paperclip.ing>
118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# 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`.
|