Appliance Manuals
Secure PDF appliance user guides for the Lovely Home dashboard. Owners upload and manage manuals; house sitters browse and read published guides from House Guide → Appliance Manuals.
Architecture
| Layer | Choice |
|---|---|
| PDF storage | Private Cloudflare R2 bucket (never public) |
| Worker binding | APPLIANCE_GUIDES |
| Metadata | Cloudflare D1 (APPLIANCE_MANUALS_DB) |
| Object keys | Server-generated opaque paths (guides/{uuid}.pdf) |
| Max upload size | 15 MB |
| Supported types | PDF only (MIME, extension, magic bytes) |
PDFs are not stored in Git, bundled in the frontend, placed in localStorage, or exposed via permanent public URLs. The Worker streams files through an authenticated endpoint.
Authorization
Two layers apply to every request:
- Cloudflare Access identity (JWT)
- Server-authoritative device session cookie
| Operation | Requirements |
|---|---|
| Upload, edit, replace, publish/hide, delete | Owner Access identity + Owner Mode device session |
| View unpublished manual or metadata | Owner Access identity + Owner Mode device session |
| List published manuals | Valid Access session + any valid device session |
| View published PDF | Valid Access session + any valid device session + manual published = true |
House sitters receive 403 Forbidden for management operations and for unpublished manuals. The Worker ignores client-supplied mode, role, or object keys.
API endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/appliance-manuals | List metadata (owner: all; sitter: published only) |
GET | /api/appliance-manuals/:id | Manual metadata |
GET | /api/appliance-manuals/:id/file | Stream PDF (Content-Disposition: inline) |
POST | /api/appliance-manuals | Create manual (multipart: fields + PDF) |
PATCH | /api/appliance-manuals/:id | Update metadata |
PUT | /api/appliance-manuals/:id/file | Replace PDF |
DELETE | /api/appliance-manuals/:id | Delete manual and PDF |
Responses never include R2 object keys, bucket names, or storage credentials.
Database migration
Migration file: worker/migrations/0001_appliance_manuals.sql
Apply locally:
cd worker
npx wrangler d1 migrations apply lovely-home-appliance-manuals --localApply to remote (Preview or Production):
cd worker
npx wrangler d1 migrations apply lovely-home-appliance-manuals --remoteCloudflare configuration
Do not make the R2 bucket public. Use separate buckets for Preview and Production so test uploads never overwrite live manuals.
Preview
- R2 bucket — create
lovely-home-appliance-guides-preview(private). - D1 database — create
lovely-home-appliance-manuals-preview. - In the Cloudflare dashboard (or Preview environment vars), bind:
APPLIANCE_GUIDES→ preview bucketAPPLIANCE_MANUALS_DB→ preview D1 database
- Run D1 migrations against the preview database.
- Deploy the Worker to the preview environment.
Update worker/wrangler.toml environment-specific overrides as needed, for example:
[env.preview]
[[env.preview.r2_buckets]]
binding = "APPLIANCE_GUIDES"
bucket_name = "lovely-home-appliance-guides-preview"
[[env.preview.d1_databases]]
binding = "APPLIANCE_MANUALS_DB"
database_name = "lovely-home-appliance-manuals-preview"
database_id = "{preview-database-id}"Replace {preview-database-id} with the ID from wrangler d1 list.
Production
- R2 bucket — create
lovely-home-appliance-guides(private). - D1 database — create
lovely-home-appliance-manuals. - Bind
APPLIANCE_GUIDESandAPPLIANCE_MANUALS_DBon the production Worker. - Run D1 migrations on the production database.
- Deploy the Worker.
The placeholder database_id in wrangler.toml must be replaced with the real production D1 ID before deploy.
Owner workflow
- Unlock Owner Mode on the tablet.
- Open Appliance Manuals from the Home launcher.
- Add manual — enter appliance details, choose category, upload PDF, optionally publish.
- Edit metadata, Replace PDF, Publish / Hide from House Sitters, or Delete (with confirmation).
- Use View to preview the uploaded guide.
Unpublished manuals remain visible to owners only.
House sitter workflow
- Open House Guide from Home or bottom navigation.
- Choose Appliance Manuals.
- Search or filter by category.
- Tap View Manual to read the PDF in the same page (scrollable pages rendered for kiosk tablets).
Backup and recovery
- D1 holds metadata (titles, publish state, opaque object keys). Back up with D1 export/backups or periodic
wrangler d1 export. - R2 holds PDF binaries. Enable object versioning or replicate to a second private bucket for disaster recovery.
- If metadata exists but R2 object is missing, republish by replacing the PDF from Owner Mode.
- If R2 cleanup fails after delete, orphaned objects may remain; check Worker logs for
appliance_manual_r2_cleanup_failedand remove orphans manually from the private bucket.
Frontend behaviour
- Owner management UI mounts only after the server confirms Owner Mode.
- Switching to House Sitter Mode clears manual state, aborts in-flight requests, and closes owner dialogs.
- PDF viewing uses an authenticated fetch and PDF.js canvas rendering in-page (no new tab — required for Fully Kiosk Browser).
- PDF.js is loaded through
src/lib/pdfjs.jsfrom the legacy build (pdfjs-dist/legacy/build/). From pdf.js 6 the standard build needs very new JavaScript (e.g.Map#getOrInsertComputed) and fails to load on older tablets and WebViews; the legacy build includes the polyfills and renders identically.tests/pdfjsLegacyBuild.test.jsguards this.
House Guide integration
Relevant help topics can link to published manuals. In guide-catalog.json, optional applianceManualTerms on a topic lists keywords matched against manual metadata (applianceName, title, manufacturer, and so on). When a sitter opens that topic, a User guide section appears with View manual if a published PDF matches.
Topics with applianceManualTerms today include dishwasher, washing machine / tumble dryer, Nest heating, hot water machine, TV / Apple TV, and hairdryer. Add terms to other topics as you upload manuals — use the appliance name and any aliases sitters might search for.
Matching uses published manuals only for house sitters. The link opens the same in-app PDF viewer used under House Guide → Appliance Manuals.
Troubleshooting
404 Not Found on /api/appliance-manuals
PR preview deployments (e.g. https://{hash}.home-dashboard-a11.pages.dev) ship the frontend only. API calls are proxied to the separate lovely-home-hub-api Worker. A 404 means that Worker is still running an older build without the appliance-manuals routes.
Fix:
- Merge or check out the branch that includes
worker/src/routes/applianceManuals.js. - Create the D1 database and private R2 bucket (see Cloudflare configuration).
- Put the real D1
database_idinworker/wrangler.toml. - Apply migrations:
npx wrangler d1 migrations apply lovely-home-appliance-manuals --remote - Deploy the Worker:
cd worker && npm run deploy
After deploy, uploads should return 201 (or 503 if bindings are missing — not 404).
503 after deploy
Bindings or migrations are missing. Confirm APPLIANCE_MANUALS_DB and APPLIANCE_GUIDES appear on the Worker in the Cloudflare dashboard, and migrations have been applied.
Limitations (v1)
- PDF files only
- No full-text search inside PDF contents
- No version history (replace overwrites the stored file)
- Sort order is assigned automatically on create; owners can adjust via API patch (
sortOrder) — UI support may follow existing patterns