House Guide CMS
Cloud-hosted House Guide content for owners to edit in the dashboard without changing git or redeploying the frontend.
Owner handbook: integrated Writing guide in Guide Editor, plus house-guide-owner-guide.md (same content for git/offline).
Architecture
| Layer | Choice |
|---|---|
| Content metadata | D1 (HOUSE_GUIDE_DB — same database as appliance manuals) |
| Uploaded photos | Private R2 bucket (GUIDE_MEDIA) |
| Bundled photos | Still served from Vite assets until replaced via upload |
| Fallback | guide-catalog.json in git when cloud content is not seeded |
Owner workflow
- Open Guide Editor (Owner Mode).
- First time only: Copy current guide to cloud — imports the bundled JSON catalog into D1.
- Pick an area → topic → edit title, blocks, and photos.
- Optionally expand Guide intro text to change the House Guide home title and subtitle.
- Save draft — stores unpublished changes.
- Publish topic or Publish all changes — makes updates visible to house sitters and guests.
Backup: Settings → Backup & restore, or Guide Editor → Export JSON / Import JSON. See site-backup.md.
Topic visibility
Each topic lists who can see it (#1181): owner plus any of family, sitter, guest, cleaner. The API returns the list as an array; guide_topics.audience stores it as a comma list. Topics saved before #1181 as guest read as owner,family,sitter,guest, and owner as owner-only. The published catalog only contains the requesting audience's topics; owners in owner mode get every topic except owner-only ones, or another audience's view with ?as=family|sitter|guest|cleaner. Owners still see owner-only topics in the editor and in draft catalog mode. Pet care is also left out for any audience whose Who sees what list doesn't include the Pet care app (#1324): every area that is about pets (id pets, an id or title saying "pet(s)", or an area named after one of the hub's pets) and every topic elsewhere whose title names one of the hub's pets (#1383, src/lib/petCare.js). The same rule runs in the catalog, so the guide, search, Ask Lottie and the offline download agree, and on the cleaner page. On useCase: both hubs that list starts as family and sitters, so short-let guests don't get pet routines. house_settings.audience_settings stores only the rows an owner set ({ version: 2, secrets, apps }, #1330); rows left out follow the use case. Blobs saved before that were full snapshots: rows equal to the standard default read as unset.
Sitters continue using House Guide as before; once cloud content is seeded and published, they read from the API instead of the static JSON bundle.
API (Owner Mode unless noted)
| Method | Path | Purpose |
|---|---|---|
GET | /api/house-guide/catalog | Published catalog (sitter + owner); owner adds ?draft=1 for draft blocks |
GET | /api/house-guide/export | Import-compatible guide JSON download (owner) |
POST | /api/house-guide/import | Import full catalog JSON (seed) |
PATCH | /api/house-guide/topics/:id | Save topic draft |
POST | /api/house-guide/topics/:id/publish | Publish one topic |
POST | /api/house-guide/publish-all | Publish all draft topics |
PATCH | /api/house-guide/settings | Update guide home intro text |
GET | /api/house-guide/media | List uploaded/bundled photo metadata (owner) |
POST | /api/house-guide/media | Upload image (multipart) |
DELETE | /api/house-guide/media/:id | Delete uploaded photo (R2 + metadata) |
GET | /api/house-guide/media/:id/file | Stream uploaded image |
POST | /api/house-guide/topics | Create a new topic (starts unpublished) |
DELETE | /api/house-guide/topics/:id | Delete a topic |
POST | /api/house-guide/categories/:id/reorder-topics | Reorder topics in an area |
Cloudflare setup
- Create R2 bucket:
lovely-home-guide-media(private). - Apply D1 migration:
npx wrangler d1 migrations apply lovely-home-appliance-manuals --remote - Deploy Worker:
cd worker && npm run deploy
HOUSE_GUIDE_DB and GUIDE_MEDIA bindings are declared in worker/wrangler.toml.
Block types in the editor
Paragraph, numbered steps, tips/warnings/notes, details lists, contact cards (with optional links), photos (pick existing or upload to R2), locations, expandable sections, and place cards. Private info blocks are preserved but not editable here.
Topics also support search keywords, appliance manual links, quick actions (Alexa routines, topic links, info panels), and topic management (create, reorder, delete). Use Photo library in the editor toolbar to browse, replace, or delete uploaded photos. Unpublished topic edits show a Draft label in the topic list.
Migrations
After pulling updates, apply new D1 migrations:
cd worker && npx wrangler d1 migrations apply lovely-home-appliance-manuals --remote