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

2.4 KiB

Raw Blame History

Compass NHS — System Overview

Purpose

The service reads the school systems for Harry and Finn. It answers three questions: what is due, what is overdue, and what important events are coming.

Sam sees both children on one page. The family receives the briefs before work is late. Nobody logs into Compass each morning.

Users

User	Role
Sam	Owner. Uses the dashboard.
Jo, Harry, Finn	Read-only. Receive the briefs.

Main Parts

Part	Function
Go service	Serves the dashboard and the Hub API. Holds the state.
SQLite store	Keeps children, items, scans, notifications and calendar pushes.
patchright scraper	Logs into Compass and fetches the pages.
n8n workflow	Runs the scan and the sends at 06:00 daily.
Apprise	Sends the briefs on Email and WhatsApp.
Home Assistant	Holds the calendar `calendar.school`.
Hub	Calls the read-only `/ask` endpoint.

The Data Flow

n8n triggers scripts/morning-brief.sh at 06:00.
The script scans Compass for each child and stores the raw pages.
The parser turns the pages into items: tasks, messages and events.
The classifier marks important events. OmniRoute helps only here.
The brief builder makes one brief per boy and one combined brief.
Apprise sends the briefs on Email and WhatsApp.
The calendar sync writes today's and future important events to Home Assistant.

Read-Only Rule

The service never writes to the school. It logs in and fetches pages only. The scraper never posts, messages or submits anything.

Fail Loudly

A missing scan or a failed scan is never an empty day. The dashboard, the briefs and /ask each state the real scan state. A failed scan says so in plain words.

Teams

Teams (FR-15) is DEFERRED. The project does not scan Teams. This is a known gap, not a defect. Compass gives the schedule, the tasks and the due dates.

Live Targets

System	Address
Dashboard	`https://school.lab.audasmedia.com.au`
Service container	`.13`, port 8792
Health	`http://127.0.0.1:8792/health`
Apprise API	`.35`, port 8210
Hub inbound	`http://192.168.20.13:8788/ask`

Repository

Git: ssh://git@gitea.lab.audasmedia.com.au:2222/sam/compass_teams_nhs.git
Branch: main
Spec: AGENTS.md
Interactive map: https://maps.lab.audasmedia.com.au/compass_teams_nhs/docs/

2.4 KiB Raw Blame History