andrei/biblical-guide.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b6620cd78d2b09d35d47a61c0e5f949a019ffb52
biblical-guide.com/docs/plans/2025-01-11-bible-reader-2025-design.md

11 KiB
Raw Blame History

2025 Modern Bible Reader Design

Date: 2025-01-11 Status: Approved Design Objective: Create a state-of-the-art, distraction-free Bible reader with comprehensive customization, offline-first capability, and seamless sync across devices.

Core Philosophy

The Bible reader is built around three non-negotiable principles:

  1. Content-first design: Text is the hero; everything else supports it
  2. Progressive disclosure: Basic reading is immediately accessible; advanced features reveal on demand
  3. Smart offline-first: Works seamlessly online and offline with automatic sync

Key Features & Requirements

1. Reading Interface & Layout

Desktop/Tablet Layout

  • Header: Minimal - book/chapter reference and reading time estimate (collapses on tablet)
  • Main text area: Full width, centered column for readability, generous margins, scalable fonts
  • Right sidebar: Chapter overview, verse numbers on hover (collapsible on tablet)
  • Bottom bar: Navigation controls (previous/next, search, settings) - subtle and de-emphasized

Mobile Layout

  • Full-screen text with header and footer hidden until needed
  • Swipe left/right: Navigate chapters (intuitive, touch-native)
  • Tap top third: Show header; tap bottom third: show navigation controls
  • Search button: Always available in floating action button (bottom right)

Touch-Optimized Navigation

  • Tap verse reference (e.g., "Genesis 1:1") → Search input pre-filled
  • Keyboard: Type book name or chapter reference with auto-complete suggestions
  • Results: Touch-friendly list with book icons, chapter counts, quick jump buttons
  • Verse numbers: Large tap targets (min 48px height on mobile)

2. Reading Customization System

Smart Preset Profiles (4 curated options)

Default: Serif font (Georgia/EB Garamond), comfortable line-height, warm background, optimized spacing

Dyslexia-friendly: Dyslexia-optimized font (e.g., Atkinson Hyperlegible), increased letter spacing, sans-serif, larger default size, muted colors

High contrast: Bold sans-serif, maximum contrast, dark background with bright text or vice versa, minimalist

Minimal: Smallest overhead, pure black text on white, no decorative elements

Full Customization Options

Users can fine-tune any preset:

  • Font family: 6-8 curated options (serif, sans-serif, dyslexia-friendly)
  • Font size: 12px-32px with live preview
  • Line height: 1.4x - 2.2x for readability
  • Letter spacing: Normal to 0.15em for spacing
  • Text alignment: Left (default), justified, center
  • Background color: Light, warm, sepia, dark mode, custom
  • Text color: Auto-adjusted based on background for contrast
  • Margins: Narrow, normal, wide (affects text width/readability)

Customization Persistence

  • Stored in localStorage (device)
  • Synced to cloud (user account)
  • Live preview as user adjusts sliders
  • "Reset to preset" button always available
  • Custom profiles can be saved

3. Layered Details Panel & Annotations

Design principle: Main text stays clean; detailed information reveals on demand.

Panel Behavior

  • Triggered by clicking/tapping a verse
  • Appears as right sidebar (desktop) or bottom sheet (mobile)
  • Verse reference sticky at top, always visible

Tabs/Accordions

  • Notes: Rich text editor inline, add/edit without leaving reading flow
  • Highlights: Color-coded (yellow, orange, pink, blue), one swipe to highlight, another to change color
  • Cross-References: Collapsible list showing related verses, tap to jump
  • Commentary: Expandable summaries, lazy-loaded, tap to expand full text

Annotation Features

  • Bookmarks: One-tap heart icon to mark verses as important
  • Highlights: Auto-saved with timestamp, searchable across all highlights
  • Personal Notes: Rich text editor with optional voice-to-text (mobile)
  • Cross-References: System generates suggestions, user can add custom links
  • Sync behavior: All annotations sync automatically when online, queued offline

4. Smart Offline & Sync Strategy

Caching Approach (Not Full Downloads)

  • On read: When user opens a chapter, it's cached to IndexedDB
  • Prefetching: Automatically cache next 2-3 chapters in background
  • Cache management: Keep last 50 chapters read (~5-10MB typical)
  • Storage limit: 50MB mobile, 200MB desktop
  • Expiration: Auto-expire chapters after 30 days or when quota exceeded

Online/Offline Detection

  • Service Worker monitors connection status
  • Seamless switching between online and offline modes
  • Status indicator in header: green (online), yellow (syncing), gray (offline)
  • User can force offline-mode for distraction-free reading

Automatic Sync Queue

  • All annotations queued locally on creation
  • Auto-sync to server when connection detected
  • Reading position synced every 30 seconds when online
  • Sync status: "Syncing...", then "Synced ✓" briefly shown
  • User can manually trigger sync from settings

Conflict Resolution

  • Strategy: Last-modified-timestamp wins
  • Safety: No data loss - version history kept server-side
  • Warning: User notified if sync fails (rare), manual sync available
  • User control: Toggle "offline-first mode" to disable auto-sync

5. Component Architecture

BibleReaderApp (main container)
├── SearchNavigator (search + auto-complete, touch-optimized)
├── ReadingView (responsive layout management)
│   ├── Header (book/chapter reference, reading time)
│   ├── MainContent (centered text column)
│   │   └── VerseRenderer (verse numbers, highlighting, click handling)
│   └── NavFooter (prev/next, mobile controls)
├── VersDetailsPanel (reveals on verse click)
│   ├── TabsContainer
│   │   ├── NotesTab (rich editor)
│   │   ├── HighlightsTab (color selection)
│   │   ├── CrossRefsTab (linked verses)
│   │   └── CommentaryTab (lazy-loaded)
├── ReadingSettings (customization presets + sliders)
├── OfflineSyncManager (background sync, status indicator)
└── ServiceWorkerManager (offline detection, cache strategies)

6. State Management & Data Flow

Local Storage

  • Current book/chapter/verse position
  • User reading preferences (font, size, colors, etc.)
  • Custom preset names and settings

IndexedDB

  • Cached Bible chapters with expiration timestamps
  • All annotations: bookmarks, highlights, notes
  • Sync queue (pending changes)
  • Reading history

Cloud/Server

  • Master copy of user data (preferences, annotations)
  • Reconciles with local state on sync
  • Manages version history for conflict resolution
  • Provides commentary and cross-reference data

Data Flow Sequence

  1. User opens app → Check IndexedDB for cached chapter
  2. If cached and fresh, render immediately (instant UX)
  3. Fetch fresh version from server in background (if online)
  4. User reads, annotations stored locally with sync timestamp
  5. Background sync worker pushes changes when connection available
  6. Service Worker manages cache invalidation and offline fallback

7. Error Handling & Resilience

  • Network failures: Toast notification, automatic retry queue
  • Sync conflicts: Timestamp-based resolution, log for user review
  • Corrupted cache: Auto-clear and re-fetch from server
  • Quota exceeded: Prompt user to clear old cached chapters
  • Service Worker issues: Graceful fallback to online-only mode

8. Success Metrics

  • Performance: First render < 500ms (cached), < 1.5s (fresh fetch)
  • Accessibility: WCAG 2.1 AA compliance
  • Mobile: Touch targets min 48px, responsive down to 320px width
  • Offline: Works without internet for last 50 chapters read
  • Sync: Auto-sync completes within 5 seconds when online
  • User satisfaction: Dyslexia-friendly preset reduces reading friction

Design Decisions Rationale

Why Smart Caching Over Full Downloads?

  • Reduces initial storage requirements (50MB vs 100+MB for full Bible)
  • Users only cache what they actually read
  • Simpler UX: no complex download management
  • Works great for mobile with limited storage

Why Presets + Full Customization?

  • Accessibility: Preset handles 90% of needs, reduces choice paralysis
  • Power users: Full control when needed
  • Discovery: Users learn what customization options exist through presets
  • Inclusivity: Dyslexia preset built-in, not an afterthought

Why Layered Panel for Details?

  • Keeps reading flow uninterrupted
  • Details don't clutter main text
  • Touch-friendly: panel slides in from bottom on mobile
  • Scalable: easy to add more annotation features later

Why Search-First Navigation?

  • Fastest for known passages (type "Genesis 1" instantly)
  • Modern pattern: matches how users navigate other apps
  • Mobile-friendly: better than scrolling long book lists
  • Supports reference system: users familiar with biblical citations

Implementation Priorities

Phase 1 (MVP): Core Reading Experience

  • Search-first navigation
  • Responsive reading layout (desktop, tablet, mobile)
  • Basic customization (presets only)
  • Verse highlighting and basic bookmarks
  • Simple offline support (cache as read)

Phase 2: Rich Annotations

  • Notes editor
  • Color-coded highlights
  • Cross-references
  • Auto-sync (offline/online detection)

Phase 3: Polish & Advanced

  • Commentary integration
  • Smart linking (theological themes)
  • Advanced customization (full sliders)
  • Sync conflict resolution
  • Analytics and reading history

Testing Strategy

Unit Tests

  • Search filtering and auto-complete logic
  • Sync queue management and conflict resolution
  • Cache expiration logic
  • Customization preset application

Integration Tests

  • Online/offline switching
  • Cache hit/miss behavior
  • Annotation persistence across sessions
  • Sync conflict resolution

E2E Tests

  • Complete reading flow (search → read → bookmark → sync)
  • Offline reading with sync on reconnection
  • Cross-device sync behavior
  • Touch navigation on mobile
  • Customization persistence

Manual Testing

  • Desktop browsers (Chrome, Firefox, Safari)
  • Mobile Safari (iOS)
  • Chrome Mobile (Android)
  • Tablet layouts (iPad, Android tablets)
  • Network throttling (fast 3G, slow 3G, offline)

Future Enhancements

  • Voice reading (text-to-speech)
  • Reading plans integration
  • Social sharing (annotated verses)
  • Collaborative notes (study groups)
  • Advanced search (full-text, by topic)
  • Statistics dashboard (chapters read, time spent)
  • Dark mode improvements (true black on OLED)
  • Predictive prefetching (learns reading patterns)

References

  • Current implementation: /root/biblical-guide/components/bible/reader.tsx
  • Offline support (started): /root/biblical-guide/components/bible/offline-bible-reader.tsx
  • Type definitions: /root/biblical-guide/types/index.ts
  • API endpoints: /root/biblical-guide/app/api/bible/
Reference in New Issue View Git Blame Copy Permalink