# 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

1. n8n triggers `scripts/morning-brief.sh` at 06:00.
2. The script scans Compass for each child and stores the raw pages.
3. The parser turns the pages into items: tasks, messages and events.
4. The classifier marks important events. OmniRoute helps only here.
5. The brief builder makes one brief per boy and one combined brief.
6. Apprise sends the briefs on Email and WhatsApp.
7. 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/`