Phase 10: publish the documentation set + tick AGENTS.md 9 of 10
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>
This commit is contained in:
117
docs/outline/03-code-map.md
Normal file
117
docs/outline/03-code-map.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user