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>
71 lines
2.4 KiB
Markdown
71 lines
2.4 KiB
Markdown
# 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/`
|