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:
- Continuous scroll — no interruption, no click-wait-click pattern.
- Progressive loading — only visible + buffer zone data is fetched, reducing memory and network cost.
- Consistent UX — every date-sectioned view behaves the same way.
- 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:
dayHydrationObserverwithrootMargin: '1200px 0px'triggers hydration before day is visible.revealDaysSentinelat bottom andrevealPreviousDaysSentinelat top expand the visible window.MediaGridcomponent receivesdaysmetadata +observeDaycallback for per-day lazy loading.showItemCountPlaceholdersinMediaGridrenders 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
MediaGridcomponent +IntersectionObserverpattern 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
IntersectionObserverperformance 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
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference