1 ADR 0048 day bucketed dynamic loading ui
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0048: Day-bucketed Dynamic Loading UI

Status: accepted Date: 2026-06-12

Context

The Plants page (/discovery/domains/{domainKey}/media) shows identified images in date-grouped sections but uses a manual "Show newer days" / "Show older days" button pagination pattern. The user clicks buttons to shift a small window (2 days at a time) through the full result set. This is inconsistent with the Timeline (/), which uses dynamic loading: day metadata is fetched first, then day items are lazy-loaded as the user scrolls using IntersectionObserver sentinels.

The Timeline's pattern is superior for media browsing because:

  1. Continuous scroll — no interruption, no click-wait-click pattern.
  2. Progressive loading — only visible + buffer zone data is fetched, reducing memory and network cost.
  3. Consistent UX — every date-sectioned view behaves the same way.
  4. Scalability — works for 10 days or 10,000 days with equal performance.

Decision

All date-sectioned media views must use the day-bucketed dynamic loading pattern established by the Timeline. This pattern has three layers:

1. Backend: Day Metadata Endpoint

Returns a list of day summaries (key, label, eyebrow, itemCount, sortTimestamp) without any media items. This is the lightweight "skeleton" that drives the UI structure.

GET /api/{resource}/days → TimelineDaysPage

Each day has a key (e.g., captured:2026-06-12 or undated), label (human-readable date), eyebrow (month/year), and itemCount.

2. Backend: Day Items Endpoint

Returns media items for a single day, fetched on demand.

GET /api/{resource}/days/{dayKey}/items → TimelinePage

The dayKey is URL-encoded since it contains : and -.

3. Frontend: IntersectionObserver Pattern

1. Fetch day metadata (days endpoint)
2. Render day section shells with itemCount placeholders
3. Observe day headers + sentinel elements with IntersectionObserver
4. When a day enters viewport → hydrate it (fetch items from day-items endpoint)
5. When a day leaves viewport far enough → optionally discard items
6. Sentinels at top/bottom trigger reveal of previous/next day windows

Key implementation details:

  • dayHydrationObserver with rootMargin: '1200px 0px' triggers hydration before day is visible.
  • revealDaysSentinel at bottom and revealPreviousDaysSentinel at top expand the visible window.
  • MediaGrid component receives days metadata + observeDay callback for per-day lazy loading.
  • showItemCountPlaceholders in MediaGrid renders placeholder squares for unloaded items.

ADR-Scope Endpoint Mapping

View Days endpoint Day items endpoint
Timeline (/) GET /api/timeline/days GET /api/timeline/days/{dayKey}/items
Discovery domain (/discovery/domains/{domainKey}/media) GET /api/discovery/domains/{domainKey}/days GET /api/discovery/domains/{domainKey}/days/{dayKey}/items
Future date-sectioned views Same pattern, adapted to domain Same pattern

Alternatives Considered

Option Summary Costs / Risks
A: Keep manual button pagination No backend changes needed Inconsistent UX, poor scalability, click-wait-click flow
B: Fetch all items upfront, client-side grouping Simple backend Fails at scale, high memory, no lazy loading
C: Day-bucketed dynamic loading (chosen) Two backend endpoints + observer pattern More implementation effort, but consistent and scalable

Consequences

  • Consistent UX. Every media view with dates behaves identically.
  • Scalable. Works for small (10 media) and large (10K+ media) collections.
  • Efficient. Only visible day content is loaded. Day metadata is lightweight.
  • Reusable. The MediaGrid component + IntersectionObserver pattern is shared across all views.
  • Standard established. Any new date-sectioned view must follow this pattern.

Revisit Triggers

  • If real-time update requirements change (currently handled by SSE events triggering visible-day refresh).
  • If a fundamentally different grouping (not by day) is needed for a new view.
  • If IntersectionObserver performance becomes a bottleneck with very high day counts (unlikely).

References

  • Timeline implementation: apps/web/src/routes/+page.svelte
  • MediaGrid component: apps/web/src/lib/components/MediaGrid.svelte
  • TimelineQueryService: apps/api/src/main/java/dev/memories/api/timeline/TimelineQueryService.java
  • DiscoveryService: apps/api/src/main/java/dev/memories/api/discovery/DiscoveryService.java