Sam Rolfe
37d82b1a0a
- internal/dashboard: classify items into overdue / due today / due this week /
no due date / messages; render the plain-text brief (FR-6, FR-7, FR-9).
- internal/store: ItemsForChild, ItemByID, DeleteItemByID, ScanSummaryForChild
and the stored-brief CRUD helpers (FR-10).
- internal/web: routes /?child=, /items/{id}, POST /items/{id}/delete,
POST /summaries/build, POST /summaries/{id}/delete, plus a per-child scan
banner (FR-12) and a phone-first server-rendered template.
- Calendar events are never "overdue": a past lesson is history, not work.
- cmd/school brief build|list; scripts/screenshot-phase5.mjs for phone evidence.
- Tests: bucket classification, stored-brief round-trip, and HTTP routes
including the NO SCAN / SCAN FAILED / healthy banner behaviour.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
119 lines
4.4 KiB
Markdown
119 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
> Build spec: [`AGENTS.md`](AGENTS.md). This repository is at **Phase 5** (the
|
|
> per-child dashboard). See §11 of the spec for the phase order.
|
|
|
|
## Status — Phase 5
|
|
|
|
Phase 5 adds the per-child dashboard: one tab per child, **overdue first**, then
|
|
due today, due this week and messages, plus the item detail screen and the
|
|
Delete actions. See [`docs/phase-5-dashboard-notes.md`](docs/phase-5-dashboard-notes.md).
|
|
|
|
```bash
|
|
# Phone-width evidence screenshots (writes under var/, git-ignored).
|
|
SCHOOL_USER=sam SCHOOL_PASS=... node scripts/screenshot-phase5.mjs
|
|
|
|
# Build a draft brief for one child.
|
|
docker exec compass-teams-nhs /app/school brief build --child Harry
|
|
```
|
|
|
|
## Status — Phase 4
|
|
|
|
Phase 4 fetches and parses **Harry and Finn** with a stored session per child,
|
|
and stores every item against the right `children.id`. See
|
|
[`docs/phase-4-both-children-notes.md`](docs/phase-4-both-children-notes.md).
|
|
|
|
```bash
|
|
make scan # both children
|
|
make scan SCAN_CHILD=Finn # one child
|
|
school session show # session state per child (metadata only, no secrets)
|
|
```
|
|
|
|
## Status — Phase 3
|
|
|
|
Phase 3 parses the raw pages stored by Phase 2 into the SQLite `items` table
|
|
(tasks, messages, events). See [`docs/phase-3-parse-notes.md`](docs/phase-3-parse-notes.md).
|
|
|
|
```bash
|
|
scripts/parse-compass.sh --child Harry --run latest --classify auto
|
|
```
|
|
|
|
## Status — Phase 1
|
|
|
|
Built and deployed on `.13`:
|
|
|
|
- Go service, SQLite schema for `children`, `items`, `scans`, `notifications`,
|
|
`session` (`internal/store/migrations/001_init.sql`).
|
|
- The service's **own session login** — a signed cookie, not SSO.
|
|
- Server-rendered **HTMX** shell using the Family Home Lab design tokens
|
|
(`internal/web/static/tokens.css`), phone-friendly with dark mode.
|
|
- `GET /health`.
|
|
- Its own container and port **8792**, behind Caddy at
|
|
`school.lab.audasmedia.com.au`.
|
|
|
|
Not built yet (later phases): the calendar write, notifications and the Hub API.
|
|
The service itself does **not** scan the school; n8n triggers the scan later.
|
|
Teams (FR-15) is a separate source.
|
|
|
|
### Fail loudly (FR-12)
|
|
|
|
A missing or failed scan is shown as an explicit warning or error, never as an
|
|
empty day. The dashboard reads the `scans` table and shows one of:
|
|
|
|
- **NO SCAN HAS RUN YET** — amber banner.
|
|
- **SCAN FAILED** — red banner with the failure on record.
|
|
- **Last scan completed** — green banner.
|
|
|
|
## Layout
|
|
|
|
```
|
|
cmd/school/ service entry point (run, parse, session, scan, items, hash-password, gen-secret)
|
|
internal/config/ environment configuration
|
|
internal/store/ SQLite: schema, migrations, queries
|
|
internal/parse/ HTML -> structured items (tasks, messages, events)
|
|
internal/llm/ OmniRoute client (importance classification only)
|
|
internal/auth/ session login (signed cookies, CSRF)
|
|
internal/web/ HTTP handlers, templates, static assets
|
|
deploy/ Caddy snippet, deployment notes, verify script
|
|
scripts/ Compass fetchers and the parse wrapper
|
|
environment.d/ env example (the real file is gitignored)
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
cp environment.d/school-service.env.example environment.d/school-service.env
|
|
chmod 600 environment.d/school-service.env # then fill in the secrets
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Generate secrets with the built image:
|
|
|
|
```bash
|
|
docker run --rm --entrypoint /app/school compass-teams-nhs/school:0.3.0-phase5 gen-secret
|
|
docker run --rm --entrypoint /app/school compass-teams-nhs/school:0.3.0-phase5 hash-password 'the-password'
|
|
```
|
|
|
|
Note: Docker Compose interpolates `$VAR` inside `env_file`. A bcrypt hash
|
|
contains `$`, so escape each one as `$$` in the env file.
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
make verify-phase1
|
|
```
|
|
|
|
It checks the container is healthy, `GET /health` returns 200, the login page
|
|
renders and a session login succeeds, and Caddy serves the public URL.
|
|
|
|
## Rules
|
|
|
|
- **Read-only against the school.** Never post, message, or submit anything.
|
|
- A failed scan must be loud — never report an empty day as "nothing due".
|
|
- School credentials and harness session state are secrets; never commit them.
|
|
- This project has its own folder, container, and port.
|