# Backlog review slices — 2026-05-12

Concrete next deliverables for review/test on BB-002, BB-003, BB-004.

---

## BB-002 — Ballbox offline/navigation review slices

Goal: prove low-risk read-only offline/navigation wins before touching authenticated/admin complexity.

### Slice 1 — Add minimal PWA shell for public pages
- Status: ready to code
- Scope:
  - add `app/manifest.ts`
  - add service worker registration client component
  - add service worker file under `public/`
  - add offline fallback page, likely `app/offline/page.tsx`
- Likely files:
  - `app/layout.tsx`
  - `public/sw.js` or `public/ballbox-sw.js`
  - `app/manifest.ts`
  - `app/offline/page.tsx`
  - optional: `public/icon-*`
- Behavior:
  - network-first for HTML navigations
  - cache visited public pages
  - offline fallback page when page not cached
  - cache-first for fonts/images/logo assets
  - versioned caches + old-cache cleanup
  - bounded cache size for pages/images
- Acceptance checks:
  - load `/`, `/clubs`, `/coaches`
  - go offline
  - revisit loaded pages successfully
  - open non-visited page and get explicit offline fallback
  - logo/icons still render offline
- Risks:
  - scope creep into authenticated/admin routes
  - overcaching dynamic pages

### Slice 2 — Restrict offline caching to public/read-only routes
- Status: ready to code after slice 1
- Scope:
  - route allowlist inside service worker
  - exclude `/admin`, `/player`, `/classes/login`, API routes
- Likely files:
  - SW file from slice 1
  - maybe helper config in `public/` or inline allowlist
- Acceptance checks:
  - `/admin` never served from stale cache
  - `/api/*` bypassed
  - public routes still work offline if visited before
- Risks:
  - path matching bugs

### Slice 3 — Replace global route feedback with local pending boundaries on public forms
- Status: ready to code
- Scope:
  - reduce reliance on global `RouteFeedback`
  - move pending UX to local submit/navigation areas first
- Likely files:
  - `components/route-feedback.tsx`
  - public form components such as `components/classes-request-form.tsx`
  - possibly `app/layout.tsx`
- Behavior:
  - no document-wide disabling for routine transitions
  - pending states live near the triggering form/button
- Acceptance checks:
  - submit flow shows local pending state only
  - no global disabling side effects
  - browser back/forward feel normal
- Risks:
  - hidden dependencies on current global listener

### Slice 4 — Scroll/history validation pass
- Status: review/test after slices 1-3
- Scope:
  - verify native App Router behavior first
  - only add custom restoration on proven broken pages
- Likely files:
  - maybe none
  - if needed: page-specific client components for list/detail restoration
- Test checklist:
  - open long page
  - navigate to child/detail page
  - browser back restores useful position
  - repeat on `/clubs`, `/coaches`, any long lists
- Rule:
  - no custom scroll code unless native behavior fails on a real surface

Recommended order:
1. Slice 1
2. Slice 2
3. Slice 4 quick validation
4. Slice 3 only where pain is real

---

## BB-003 — Pi web offline/navigation review slices

Goal: improve offline use on low-risk surfaces without breaking dynamic tools.

Important current fact:
- `/var/www/portal/sw.js` already exists
- current portal SW is simple cache-first/assets + network-fallback-to-index
- it is a base to refine, not start from zero

### Slice 1 — Harden portal service worker
- Status: ready to code
- Scope:
  - upgrade existing `/var/www/portal/sw.js`
  - split caches by core/pages/assets
  - add explicit offline fallback page
  - add bounded cache cleanup
  - make HTML route handling network-first + cached fallback
- Likely files:
  - `/var/www/portal/sw.js`
  - `/var/www/portal/index.html`
  - new `/var/www/portal/offline.html`
  - `/var/www/portal/manifest.json`
- Acceptance checks:
  - visit `/`
  - go offline
  - portal opens
  - previously opened linked surfaces resolve when cached
  - noncached page gets offline fallback, not broken blank shell
- Risks:
  - current manifest file looks non-JSON-valid and should be checked
  - portal root and subpath behavior may differ

### Slice 2 — Add offline shell for `/calistenia/`
- Status: ready to code
- Scope:
  - service worker scoped to `/calistenia/`
  - cache app shell + visited pages/assets
- Likely files:
  - `/home/sebas/clawd/web/calistenia/...`
  - maybe new `sw.js` and `manifest.json`
- Acceptance checks:
  - visit `/calistenia/`
  - reload offline
  - shell opens and visited content still works
- Risks:
  - unknown app build structure until inspected during coding

### Slice 3 — Read-only offline shell for `/wifi-tracker/`
- Status: ready to code
- Scope:
  - keep API network-only
  - cache HTML/CSS/JS shell and last successful JSON snapshot
  - show stale/offline badge when rendering cached snapshot
- Likely files:
  - `/var/www/wifi-tracker/index.html`
  - maybe `/var/www/wifi-tracker/sw.js`
  - maybe snapshot endpoint or current `summary.json`
- Acceptance checks:
  - online load renders current data
  - offline reload still shows last known snapshot
  - UI clearly says stale/offline
- Risks:
  - stale data confusion if badge is weak

### Slice 4 — Read-only offline shell for `/domotics/`
- Status: ready to code after wifi-tracker pattern
- Scope:
  - cache shell only
  - do not fake successful controls offline
  - disable control actions when API unavailable
- Likely files:
  - `/var/www/domotics/index.html`
  - maybe `/var/www/domotics/sw.js`
- Acceptance checks:
  - page opens offline
  - device list may show last known state if cached
  - control buttons clearly fail or disable offline
- Risks:
  - misleading control affordances during outage/offline

Do not prioritize now:
- `/files/`
- `/reports/`
- `/mp3-share/`
- `/pi/`

Recommended order:
1. Slice 1
2. Slice 2
3. Slice 3
4. Slice 4

---

## BB-004 — OSS self-hosted RSS reader review plan

Constraint:
- no paid options

Minimal bar:
- self-hosted
- free/OSS
- mobile-friendly web UI
- feed import/subscription
- server-side read/unread sync
- article view usable on phone
- enough browser caching/service-worker room to support preloaded offline reading later

### Shortlist

#### 1. Miniflux
- Why shortlist:
  - mature OSS
  - common self-hosted choice
  - strong import/admin basics
  - mobile web usable
  - - Likely fit:
  - best lightweight first trial
- Main concern:
  - offline UX likely still needs a browser/PWA layer

#### 2. Miniflux
- Why shortlist:
  - simple
  - efficient
  - single-binary Go app
  - clean UI
- Likely fit:
  - best low-ops baseline
- Main concern:
  - may undershoot richer offline/save behavior without extra work

#### 3. Tiny Tiny RSS
- Why shortlist:
  - mature
  - flexible
  - plugin ecosystem
- Likely fit:
  - best if flexibility beats UX simplicity
- Main concern:
  - heavier feel and older UX

#### 4. CommaFeed
- Why shortlist:
  - reader-focused UI
  - decent self-hosted option
- Likely fit:
  - test if reading UX feels better than TT-RSS
- Main concern:
  - Java runtime overhead

#### 5. Selfoss
- Why shortlist:
  - lightweight
  - simple
- Likely fit:
  - fallback lightweight option only
- Main concern:
  - lower confidence on momentum/fit vs top two

### Recommended trial order
1. Miniflux
2. Tiny Tiny RSS
3. CommaFeed
4. Selfoss

### Trial checklist for each
- Install locally behind nginx or direct localhost
- Import a representative feed set
- Test mobile web on phone
- Mark read/unread across devices
- Save 20-50 articles for later reading
- Visit those articles once online, then test phone offline/airplane mode
- Check if visited articles remain readable from browser cache
- Check whether article list stays usable offline
- Check whether UI degrades cleanly when refresh fails
- Estimate ops cost: runtime, storage, update friction

### Reviewable implementation slice

#### Slice 1 — Stand up Miniflux trial instance
- Status: ready to code
- Scope:
  - local deploy only
  - seed with sample feeds
  - put behind nginx subpath if clean, otherwise localhost first
- Acceptance checks:
  - working reader on phone
  - import/export works
  - read state persists
- Decision gate:
  - if Miniflux is good enough, stop and add offline shell later
  - if not, trial Miniflux next

#### Slice 2 — Add offline-friendly shell around winner
- Status: after winner chosen
- Scope:
  - service worker/browser caching strategy for article pages already opened
  - explicit offline page and stale indicators
- Acceptance checks:
  - flight-mode revisit of loaded articles works
  - no fake freshness claims

---

## Suggested execution if running all three in parallel

1. Code BB-003 slice 1 first on this machine
   - fastest validation path because portal already has SW
2. Code BB-002 slice 1 in Ballbox
   - same pattern, separate app
3. Stand up BB-004 RSS reader trial
   - parallel infra/product validation

## Review checkpoints for Sebas

- After BB-003 slice 1:
  - test portal offline from phone
- After BB-002 slice 1:
  - test Ballbox public pages offline/back-forward behavior
- After BB-004 slice 1:
  - test feed reading UX on phone and in airplane mode