Files

Sam Rolfe b4bbd6d3f9 Phase 9: publish the documentation set (README, map, Outline, Vikunja)

- README: Phase 9 status, the architecture diagram + map link, and the
  explicit "Teams (FR-15) is DEFERRED" statement.
- docs/architecture.mmd + docs/diagrams/architecture.png (mmdc).
- docs/archify/architecture.architecture.json -> docs/architecture-map.html
  (Archify showcase, 9/9 checks).
- docs/outline/: the five AI-context documents (STE style).
- docs/vikunja-tasks.json: the live Vikunja board (project 21).

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-10-15 20:00:23 +11:00

3.5 KiB

Raw Blame History

Compass NHS — Code Map

Module

gitea.lab.audasmedia.com.au/sam/compass_teams_nhs

Language: Go 1.25. Database: SQLite through modernc.org/sqlite. Passwords use golang.org/x/crypto/bcrypt. There is no other direct dependency.

Entry Point

cmd/school/main.go holds the entry point. The first argument selects a subcommand. With no argument it starts the HTTP service.

Subcommand	Function
`run` (default)	Starts the HTTP service, migrates the schema and seeds the children.
`parse`	Turns stored raw pages into items.
`session`	Shows or clears the harness session per child.
`scan`	Fetches and parses one child or both.
`items`	Reads or deletes items.
`brief`	Builds a brief.
`notify`	Sends briefs and shows the send status.
`calendar`	Pushes events to Home Assistant.
`hash-password`	Prints a bcrypt hash.
`gen-secret`	Prints a fresh secret.
`version`	Prints the version.

Folders

Folder	Function
`cmd/school/`	One file per subcommand plus `main.go`.
`internal/web/`	HTTP server, handlers, HTMX templates, static assets. Holds `hub_api.go`.
`internal/auth/`	Session login with signed cookies and CSRF.
`internal/store/`	SQLite open, migrations and queries.
`internal/store/migrations/`	`001_init`, `002_items_parse`, `003_calendar`, `004_notifications_send`.
`internal/parse/`	HTML to items. Readings for tasks, news, calendar and importance.
`internal/llm/`	OmniRoute client for importance classification only.
`internal/dashboard/`	Builds the per-child buckets. Classifies overdue and due-today.
`internal/brief/`	Builds and delivers the morning briefs.
`internal/apprise/`	Apprise API client. Uses tags and redacts errors.
`internal/calendar/`	Home Assistant client and the idempotent sync.
`internal/hub/`	The Hub contract: capabilities and read-only answers.
`internal/config/`	Reads the environment.
`deploy/`	Caddy snippet, n8n workflow, import and key scripts, verify scripts.
`scripts/`	Scrapers, parse and morning-brief wrappers, calendar push.

The Read-Only Boundary

internal/hub depends on a Reader interface. The interface has three read methods and no write method. Test TestHubAskReadsOnly proves that /ask does not change the items, scans or notifications row counts.

The Scraper

scripts/compass-fetch-patchright.mjs logs into Compass with patchright. The login POST meets a Cloudflare managed challenge. patchright, a headless Playwright build, passes the challenge. The pi-browser-harness does not.

The Compass parent login required no two-factor code during the Phase 2 proof.

Database Tables

Table	Holds
`children`	id, name, year, Compass id.
`items`	Child, type, subject, teacher, title, body, due date, URL.
`scans`	Start time, child, pages fetched, items found, error.
`notifications`	Recipient, scope, summary, channel, status, sent time.
`session`	Harness session state per child.
`calendar_pushes`	Calendar write attempts, result and error.

The raw Compass pages are not in the database. The fetcher writes them to var/raw/<child>/<timestamp>/ on the host. Each folder holds the HTML, a meta file per page, and a manifest with a SHA-256 and a byte count per page.

Tests

Run make test. The suite uses standard Go tests. The tests cover the store, the parser, the dashboard buckets, the brief, the Apprise client, the calendar sync, the Hub API and the read-only rule.

3.5 KiB Raw Blame History