NestQuest/docs/ARCHITECTURE.md

# NestQuest Architecture

Status: approved direction (2026-09-21). This document supersedes the
single-process design implied by Features 01–14, in which the Home Assistant
integration owned the database and the parent admin surface was planned as a
Lovelace card inside Home Assistant.

## 1. Why this changed

The original design put everything inside the Home Assistant integration: the
SQLite database, the business logic, the kid panel cards, and (planned) the
parent admin card. Three problems surfaced:

1. **The panel needed hand configuration.** Standing up the kid panel required
   hand-writing card YAML (`child_order`, `quest_log_path`, `board_path`) and
   hand-creating a Lovelace dashboard. A fresh install rendered nothing.
2. **The admin surface fought Home Assistant.** The admin design
   (`design/ADMIN-SPEC.md`) is drawn at 390×844 — it is a phone app. Trapping it
   inside a Lovelace card meant fighting HA's UI constraints for a mobile-first
   experience.
3. **Data was locked to one process.** A standalone admin web app cannot reach a
   SQLite file inside Home Assistant's config directory.

The re-imagined design keeps the panel in Home Assistant (TouchHub loads an HA
dashboard), moves data ownership to a standalone API service, and promotes the
admin surface to a standalone mobile-first PWA.

## 2. Target architecture

```
 DAKboard TouchHub
       │  (loads an HA dashboard URL)
       ▼
 HA box                                        API box
 ┌───────────────────────────────┐            ┌───────────────────────────────────┐
 │ Lovelace panel dashboard      │            │ reverse proxy (TLS)               │
 │  ├ nestquest-party-board-card │  service   │  ├ /api/v1/panel/*   LAN-only     │
 │  └ nestquest-quest-log-card   │  token     │  └ /api/v1/admin/*   public       │
 │                               │ ─────────▶ │ FastAPI (imports core/)           │
 │ NestQuest integration         │            │  └ SQLite (owned here)            │
 │  (thin client, no database)   │ ◀───────── │ Authentik (OIDC)                  │
 │  sensors + HA bus events      │  SSE       └───────────────────────────────────┘
 └───────────────────────────────┘                          ▲
                                            PWA ───────────┘
                                  https://nestquest.cubecraftlabs.com
```

One owner of the data (the API). Two clients (the HA integration, the PWA).

## 3. Data ownership

**The API service is the only writer.** The HA integration never opens the
database; it reads a snapshot and posts completions. This removes the
two-writer problem entirely.

- **Storage:** SQLite on the API box. Single household, trivial concurrency,
  and the existing schema, migrations, and DAO tests are already SQLite. Postgres
  buys nothing at this scale.
- **Schema:** unchanged. The cutover from the current HA-hosted database is a
  file copy — same schema, same migration version.
- **Backups:** continuous replication (e.g. Litestream) plus a proven restore.
  A configured-but-untested backup is not a backup.

### Presence model (schema 9)

A child has **zero or more** presence patterns, stored one row each in
`presence_patterns` (`child_id` is not unique):

| Column | Meaning |
|---|---|
| `name` | Label shown in the admin PWA, not blank |
| `kind` | `home` or `away` — what the pattern claims on the days it covers |
| `cycle_length_weeks` | 1–4; the pattern's own repeating cycle |
| `anchor_date` | ISO date that starts week 1 of the pattern's cycle |
| `pattern` | Pipe-separated weekday sets, one CSV segment per cycle week, weekdays **Monday=0 .. Sunday=6** (e.g. `0,2,4\|1,3`); an empty segment covers no day that week |

Cycle position is anchor-date arithmetic per pattern — **never** ISO week
numbers or week parity (D-004). A child's presence on a date is decided
first match wins:

1. A presence override covering the date — its flag is the answer.
2. Any `away` pattern covers the date — **away**.
3. Any `home` pattern covers the date — **present**.
4. The child has at least one `home` pattern — **away** (a home pattern lists
   the days the child is home; every other day is away).
5. Otherwise (only `away` patterns, or no patterns) — **present**.

The core presence engine, the snapshot's `present_today`, the materialiser's
skip-on-away-days rule, and the admin PWA's month grid all apply this order.
The admin plane manages patterns with
`GET`/`POST /api/v1/admin/children/{child_id}/presence-patterns` and
`PATCH`/`DELETE /api/v1/admin/presence-patterns/{pattern_id}`.

**Migration 9** replaced the older one-schedule-per-child table: it creates
`presence_patterns`, copies every old schedule row into a `home` pattern
named `Home schedule` (cycle length, anchor date and weekday sets
unchanged, row id kept), and drops the old table, all in one transaction.
A lone `home` pattern answers exactly as the old schedule did, so no
child's presence changes. The drop is one-way and 0.7.1 refuses a
version-9 database; see the rollback step in `deploy/RUNBOOK.md` §11.

### Application timezone (manual, admin-set)

The application timezone is set **manually by an admin from the admin
app** — the Settings screen's timezone picker, which reads and writes the
`timezone` field of `GET`/`PATCH /api/v1/admin/settings`. Nothing sets it
automatically: there is no Home Assistant zone adoption, no browser-zone
auto-detect, and no auto-save when a screen loads. Only an admin's `PATCH`
ever changes the stored value.

The stored value is the **single source of local-time truth for the whole
application.** The API reads its one clock and re-expresses it in that zone
(`NestQuestSettings.household_now`), so every local date and time comes
from it:

- the panel snapshot's today and overdue state, and both panel cards'
  visible dates and clocks (the snapshot publishes the zone as `timezone`,
  which the integration exposes on the household rollup sensor);
- completion timestamps (the local completion date and the on-time check);
- the missed-sweep scheduler's household rollover;
- every admin read, and the admin app's local-time formatting.

**Empty means the API host's local zone.** While `timezone` is empty the
API reads its clock in the host's local time, and publishes that zone as
the effective zone (`api/host_zone.py`: the `effective_timezone` field of
the admin settings response and the snapshot's `timezone`) until an admin
sets one. No code fills the empty value in.

**A save re-plans the sweep.** An admin save that changes `timezone` or
`day_rollover_time` notifies the running missed-sweep scheduler
(`MissedSweepScheduler.settings_changed`, under its settings lock), which
re-plans its next sweep for the new household rollover.

## 4. Authentication: two planes

The kid panel and the admin PWA have opposite trust levels, so they use
separate credentials and separate network exposure.

### Panel plane (machine)

- **Credential:** a static service token.
- **Exposure:** `/api/v1/panel/*` is reachable **only from the LAN**.
- **Grants:** read the snapshot, and the single open write — complete a quest as
  `actor: panel` with the tapped `actor_child_id`.
- **Refused:** admin routes reject the service token outright, not merely as a
  non-admin. The internet cannot reach these routes at all.

This preserves the original fail-closed boundary: the kiosk can complete a
quest and nothing else.

### Admin plane (human)

- **Credential:** an Authentik OIDC JWT (authorization code + PKCE).
- **Exposure:** `/api/v1/admin/*` is internet-facing behind Authentik.
- **Grants:** everything a parent can do — definitions, assignment, presence,
  children, un-complete, history, export, settings, regenerate.
- **Gate:** the API validates the JWT (issuer, audience, JWKS signature, expiry)
  and requires membership in the `nestquest-admins` group. The Authentik group
  is the single source of truth for "who is a parent", replacing the
  integration-side admin allowlist.

## 5. Components

### `core/` — domain library

The extracted domain layer: schema, migrations, database access, DAOs, the pure
recurrence and presence engines, materialization, completion, event payload
construction, and the children/definitions/allowlist business layers. **No
Home Assistant imports.** Consumed by both the API and (during transition) the
integration. This is where the ~1500 existing tests live after extraction.

### `api/` — NestQuest API

A FastAPI service importing `core/`. Owns the database. Serves the panel and
admin planes, validates Authentik tokens, and publishes a transition event
stream (SSE) that the integration consumes. No business logic in route handlers.

### `custom_components/nestquest/` — HA integration (client)

A thin client. Polls the snapshot and builds the existing sensors; subscribes to
the SSE stream and re-fires the four HA bus events; proxies the panel completion.
Holds a last-good snapshot cache so a brief API outage does not blank the panel.
Owns no database and no business logic.

### `panel/` — Lovelace cards and dashboard strategy

The two kid-facing Lit cards plus a dashboard strategy that generates the panel
views at render time. Cards auto-discover children, so no `child_order` is
required; the strategy computes navigation paths, so `quest_log_path` and
`board_path` are not required.

### `admin/` — Admin PWA

A React progressive web app implementing `design/ADMIN-SPEC.md`, authenticated
via Authentik OIDC, installable on a phone. The only admin surface.

## 6. Zero-configuration panel

A fresh install should show the panel with no YAML:

1. **Auto-discovery.** The party-board card reads an ordered child list from a
   household entity attribute instead of a configured `child_order`.
2. **Dashboard strategy.** A Lovelace strategy generates a party-board view and
   one quest-log view per child, wiring navigation between them, so paths are
   computed rather than configured. Explicit configuration still wins if a user
   supplies it.
3. **Auto-registration.** The integration registers the dashboard on first
   setup, so there is no manual dashboard step.

## 7. Home Assistant surface preserved

The re-imagining must not break what already works:

- **Sensors:** the per-child and household sensor entity_ids and the per-child
  instance attribute payload shape are unchanged. The panel cards and the four
  blueprints depend on them.
- **Events:** the four HA bus events (`nestquest_quest_completed`,
  `nestquest_quest_uncompleted`, `nestquest_quest_missed`,
  `nestquest_child_day_complete`) keep firing with their documented payloads.
  They are now driven by the API's transition stream rather than by local
  service handlers.
- **Blueprints:** the morning summary, afternoon reminder, end-of-day report, and
  day-complete celebration continue to work with no change.

## 8. Events without an HA token on the API box

The API publishes transitions on an SSE stream; the integration subscribes and
re-fires the HA bus events locally. This deliberately avoids storing a Home
Assistant long-lived token on the API box, which would grant full HA access.

## 9. Migration phases

Mapped to the Maestro features:

| Phase | Feature | Outcome |
|---|---|---|
| 1 | 15 — Domain Core Extraction | `core/` runs with no HA imports; one implementation of the rules |
| 2 | 16 — NestQuest API Service | Panel and admin planes served with two-plane auth |
| 3 | 17 — API Deployment and Identity | TLS, Authentik, backups, network separation |
| 4 | 18 — HA Integration as API Client | Integration becomes a client; entity/event surface preserved |
| 5 | 19 — Admin PWA | Mobile-first React PWA replaces the admin card |
| 6 | 20 — Zero-Config Panel Dashboard | Panel installs itself; navigation and animations match the mockups |

Cutover: copy the existing SQLite file to the API box (same schema).

## 10. Locked decisions

- **API on its own box** — separate from Home Assistant.
- **Authentik** (`https://auth.cubecraftlabs.com`) for admin identity; a
  `nestquest-admins` group is the admin source of truth.
- **Single household** — no tenant column, no multi-household auth.
- **React** for the admin PWA.
- **Drop the HA admin services** — the PWA is the only admin surface. The panel
  completion path stays.
- **SQLite on the API box** initially; Postgres only if multi-household ever
  becomes real.

## 11. Preserved vs. changed

**Preserved:** the tested Python domain layer, the panel card designs and
tokens, the sensor and event contract, the completion model, the append-only
event log, the panel's fail-closed "complete only" boundary.

**Changed:** data ownership moves to the API; the integration becomes a client;
the admin card becomes a PWA; panel cards become config-free with a
strategy-generated dashboard.

**New:** the API service, Authentik-gated admin auth, the PWA, and a
last-good-snapshot cache in the integration.

**Cost:** two new deployables (the API and the PWA) and one new box. Accepted
knowingly in exchange for a self-installing panel, an admin surface that is not
fighting HA's UI, and a data layer with real auth in front of it.