Sam Rolfe
b4bbd6d3f9
- 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>
83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
# 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.
|