---
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.