138 lines
4.6 KiB
Markdown
138 lines
4.6 KiB
Markdown
---
|
|
type: note
|
|
proposed_folder: 200 projects/Tools Software WebUI
|
|
proposed_toc: "100 Table of Contents/Projects.md → Tools & Software"
|
|
proposed_tags:
|
|
- project
|
|
- family
|
|
- architecture
|
|
- go
|
|
- compass
|
|
- finn
|
|
- school
|
|
- service
|
|
- sqlite
|
|
- htmx
|
|
- playwright
|
|
- apprise
|
|
confidence: 0.38
|
|
approved: false
|
|
proposed_for: 242a5e5a3d38
|
|
created: "2026-10-15 20:00"
|
|
tags:
|
|
- project
|
|
- family
|
|
- school
|
|
- compass
|
|
- go
|
|
- sqlite
|
|
- htmx
|
|
- playwright
|
|
- apprise
|
|
aliases:
|
|
- Compass NHS
|
|
- School Service
|
|
skills:
|
|
- Go service with no heavy framework
|
|
- SQLite data modelling with versioned migrations
|
|
- HTMX server-rendered dashboard with no build step
|
|
- Headless browser automation (patchright) past a Cloudflare challenge
|
|
- HTML parsing into structured items
|
|
- Read-only HTTP contract for another service (the Hub)
|
|
- Docker and Caddy deployment
|
|
- n8n scheduling with a restricted SSH trigger
|
|
tools:
|
|
- Go
|
|
- SQLite
|
|
- HTMX
|
|
- patchright (headless Playwright)
|
|
- Docker
|
|
- Caddy
|
|
- n8n
|
|
- Apprise
|
|
- Home Assistant
|
|
- OmniRoute
|
|
---
|
|
|
|
# [[Compass NHS — Harry and Finn's School Service]]
|
|
|
|
## What is this project?
|
|
|
|
This project watches the school for Harry and Finn. Each morning it reads the
|
|
school system, Compass, and works out what each boy has due. It shows Sam one
|
|
page with what is overdue first. It then sends each boy his own short brief, and
|
|
one combined brief to Jo and Sam.
|
|
|
|
The point is simple. Nobody has to log into Compass in the morning. The family
|
|
learns about late work **before** it is late, not after.
|
|
|
|
## What it does
|
|
|
|
- **Reads Compass** for both children, twice a day apart or on demand.
|
|
- **Stores every item**: homework, tasks, notices and school events, each against
|
|
the right child.
|
|
- **Finds overdue work** and puts it first. Then due today, then due this week.
|
|
- **Shows a dashboard** with one tab per child. It works on a phone.
|
|
- **Writes important school events** to the Home Assistant calendar
|
|
`calendar.school`.
|
|
- **Sends the morning briefs** at 6:00am on Email and WhatsApp.
|
|
- **Answers the Hub** to a question such as "what does Harry have on today at
|
|
school?" That path is read-only.
|
|
|
|
## Why it matters (what it shows)
|
|
|
|
This is a small but complete home-lab product, not a script. The service is one
|
|
Go binary with SQLite. It has its own container, its own port, its own login and
|
|
its own Caddy route. It is read-only against the school: it logs in and reads,
|
|
and it never posts or messages.
|
|
|
|
The interesting engineering part is the login. Compass sits behind **Cloudflare**,
|
|
and the login form is protected by a managed bot challenge. A normal headless
|
|
browser gets a 403. The project uses **patchright**, a headless Playwright build
|
|
that behaves enough like a real browser to pass the challenge. The parent login
|
|
needed **no** two-factor code.
|
|
|
|
The other deliberate design is honesty about failure. A failed scan must never
|
|
look like a quiet day with no homework. The dashboard, the briefs and the Hub
|
|
answer all state the real scan state in plain words.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
N8N["n8n on .13<br/>06:00 daily trigger"] --> SVC["Compass / NHS service<br/>Go + SQLite :8792"]
|
|
SAM["Sam<br/>browser dashboard"] --> CADDY["Caddy on .35"] --> SVC
|
|
SVC -->|scan| PATCH["patchright scraper"] -->|login + pages| COMPASS["Compass NHS<br/>read-only"]
|
|
SVC -->|"create event"| HA["Home Assistant<br/>calendar.school"]
|
|
SVC -->|briefs| APPRISE["Apprise .35:8210<br/>Email + WhatsApp"]
|
|
APPRISE --> BOYS["Harry and Finn<br/>per-boy brief"]
|
|
APPRISE --> PARENTS["Jo and Sam<br/>combined brief"]
|
|
HUB["Hub :8788<br/>read-only /ask"] --> SVC
|
|
```
|
|
|
|
## What is still missing (state it plainly)
|
|
|
|
**Teams (FR-15) is DEFERRED.** The project does not scan Teams for homework. This
|
|
is a known gap that the brief set aside on purpose. Everything else in the build
|
|
spec is built, deployed and running. Compass alone already answers what is due
|
|
and overdue.
|
|
|
|
## Where it lives
|
|
|
|
- **Code**: Gitea repo `sam/compass_teams_nhs` (`main`).
|
|
- **Live**: <https://school.lab.audasmedia.com.au> — its own container on `.13`,
|
|
port 8792, behind Caddy on `.35`.
|
|
- **Interactive map**:
|
|
<https://maps.lab.audasmedia.com.au/compass_teams_nhs/docs/>
|
|
- **AI context**: `docs/outline/` in the repo, and the Outline collection
|
|
*Compass / NHS (School)*.
|
|
- **Tasks**: Vikunja project **Compass / NHS (School)** (id 21).
|
|
- **Diagram source**: `docs/architecture.mmd`, rendered to
|
|
`docs/diagrams/architecture.png`.
|
|
|
|
## Status
|
|
|
|
Built and deployed. Phases 1 to 9 are done. Teams (FR-15) is deferred. The service
|
|
scans both children, shows overdue work first, writes important events to the
|
|
calendar, and sends the briefs every morning at 6:00am.
|