289 lines
11 KiB
Markdown
289 lines
11 KiB
Markdown
# 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/`
|