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>
This commit is contained in:
2026-10-15 19:58:55 +11:00
parent 06f759c37b
commit b4bbd6d3f9
11 changed files with 14534 additions and 6 deletions

View File

@@ -1,11 +1,71 @@
# Compass / NHS
A school service for Harry and Finn: **Compass** for the daily schedule and
notices, **Teams** for homework and assignments. It stores what is due per child,
puts overdue work first, and tells the family before work is late.
A school service for Harry and Finn: **Compass** gives the daily schedule, the
homework and the notices. It stores what is due per child, puts overdue work
first, and tells the family before work is late.
> Build spec: [`AGENTS.md`](AGENTS.md). This repository is at **Phase 8** (the
> Hub API). See §11 of the spec for the phase order.
> **Teams (FR-15) is DEFERRED.** No Teams section is scanned. Compass answers
> what is due and overdue. This is a known gap, not a defect.
> Build spec: [`AGENTS.md`](AGENTS.md). This repository is at **Phase 9**
> (documentation). See §11 of the spec for the phase order.
## Status — Phase 9
Phase 9 publishes the project documentation across five places.
| Layer | Artifact | Location |
|---|---|---|
| Technical README | This file | the Gitea repo |
| Architecture source | [`docs/architecture.mmd`](docs/architecture.mmd) | repo |
| Rendered diagram | [`docs/diagrams/architecture.png`](docs/diagrams/architecture.png) | repo |
| Interactive map | [`docs/architecture-map.html`](docs/architecture-map.html) | <https://maps.lab.audasmedia.com.au/compass_teams_nhs/docs/> |
| Human note | Obsidian `010 inbox/` on `.27` | filed by the sorter |
| AI context | [`docs/outline/`](docs/outline/) | Outline collection *Compass / NHS (School)* |
| Tasks | [`docs/vikunja-tasks.json`](docs/vikunja-tasks.json) | Vikunja project id 21 |
The daily trigger is **06:00** in `Australia/Melbourne` (n8n). The briefs go out
on **Email and WhatsApp** through Apprise on `.35:8210`: one brief per boy, plus
one combined brief to Jo and Sam. Important school events go to the Home
Assistant Local Calendar `calendar.school`. The Hub reads items through the
read-only `POST /ask` contract.
The accepted scraper is **patchright** (headless Playwright), not the
pi-browser-harness: the harness cannot pass the Cloudflare managed challenge on
the Compass login POST. The Compass parent login required **no** two-factor code
during the Phase 2 proof.
## Architecture
```mermaid
flowchart LR
N8N["n8n on .13<br/>06:00 daily trigger"]
SAM["Sam<br/>browser dashboard"]
CADDY["Caddy on .35<br/>school.lab.audasmedia.com.au"]
SVC["Compass / NHS service<br/>Go + SQLite :8792"]
PATCH["patchright scraper<br/>headless Playwright"]
COMPASS["Compass NHS<br/>read-only login + pages"]
OMNI["OmniRoute<br/>importance classification"]
HA["Home Assistant calendar<br/>calendar.school"]
APPRISE["Apprise on .35:8210<br/>Email + WhatsApp"]
BOYS["Harry and Finn<br/>per-boy morning brief"]
PARENTS["Jo and Sam<br/>combined morning brief"]
HUB["Hub :8788<br/>read-only /ask"]
N8N -->|"scripts/morning-brief.sh"| SVC
SAM -->|HTTPS| CADDY
CADDY --> SVC
SVC -->|scan| PATCH
PATCH -->|"login + fetch pages"| COMPASS
SVC -.->|"important only"| OMNI
SVC -->|"create event"| HA
SVC -->|briefs| APPRISE
APPRISE -->|"email + WhatsApp"| BOYS
APPRISE -->|"email + WhatsApp"| PARENTS
HUB -->|"Bearer /ask"| SVC
```
*Interactive map:* <https://maps.lab.audasmedia.com.au/compass_teams_nhs/docs/>
## Status — Phase 8
@@ -126,7 +186,7 @@ Built and deployed on `.13`:
- Its own container and port **8792**, behind Caddy at
`school.lab.audasmedia.com.au`.
Not built yet (later phases): Teams (FR-15) and the Phase 9 documentation set.
Not built yet: Teams (FR-15). It is deferred on purpose.
The service itself does **not** scan the school; n8n triggers the scan.
### Fail loudly (FR-12)
@@ -155,6 +215,7 @@ internal/web/ HTTP handlers, templates, static assets
deploy/ Caddy snippet, the n8n workflow, deployment notes, verify script
scripts/ Compass fetchers, the parse and morning-brief wrappers, the calendar push
environment.d/ env example (the real file is gitignored)
docs/ phase notes, the architecture source and map, the Outline set, Vikunja tasks
```
## Run