Discovery Journey

How users discover and absorb scripture through browsing and reading.

Overview

Geetanjali serves two user modes:

Mode User Intent Experience
Seeking “Find a verse about duty” Verse Browser — filter, explore
Reading “Read Chapter 2 in order” Reading Mode — sequential, immersive

Both modes provide access to 701 verses across 18 chapters with Sanskrit text, transliterations, and translations.

Verse Browser

Grid-based exploration for discovery and research.

┌──────────────────────────────────────────────────────────────┐
│  /verses                                       [Reading Mode]│
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  [Featured] [All]    [Chapter ▼]    [Topic Pills...]         │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│    ┌─────────────┐   ┌─────────────┐   ┌─────────────┐       │
│    │ ★ 2.47      │   │   3.19      │   │ ★ 2.48      │       │
│    │  Sanskrit   │   │  Sanskrit   │   │  Sanskrit   │       │
│    ├─────────────┤   ├─────────────┤   ├─────────────┤       │
│    │ Translation │   │ Translation │   │ Translation │       │
│    │ [tag] [tag] │   │ [tag] [tag] │   │ [tag] [tag] │       │
│    └─────────────┘   └─────────────┘   └─────────────┘       │
│                                                              │
│                      [ Continue ]                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Features:

Card → Detail Flow:

flowchart LR
    A[Verse Card] -->|Click| B[Verse Detail]
    B -->|← →| C[Adjacent Verses]
    B -->|View Chapter| D[Reading Mode]
    B -->|Tag Click| E[Filtered Grid]

Verse Detail

Single verse deep-dive with full context.

┌──────────────────────────────────────────────────────────────┐
│  [←]  Chapter 2: Sankhya Yoga              Verse 47 of 72    │
│       ████████████████████░░░░░░░░░░ 65%                     │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│                            ॐ                                 │
│         कर्मण्येवाधिकारस्ते मा फलेषु कदाचन।                              │
│         मा कर्मफलहेतुर्भूर्मा ते सङ्गोऽस्त्वकर्मणि॥                         │
│                                  ॥ २.४७ ॥                    │
│                                                              │
│   ┌─ Leadership Insight ─────────────────────────────────┐   │
│   │ Focus on your duty without attachment to outcomes.   │   │
│   │ Right action done for its own sake brings clarity.   │   │
│   └──────────────────────────────────────────────────────┘   │
│                                                              │
│   [Karma Yoga →]  [Detachment →]  [Nishkama Karma →]         │
│                                                              │
│   ┌─ Hindi ──────────────────────────────────────────────┐   │
│   │ कर्म करने में ही तेरा अधिकार है...                             │   │
│   └──────────────────────────────────────────────────────┘   │
│                                                              │
│   ┌─ English ────────────────────────────────────────────┐   │
│   │ You have the right to work only, but never to its    │   │
│   │ fruits...                — Swami Gambirananda        │   │
│   └──────────────────────────────────────────────────────┘   │
│                                                              │
│   [Show More Translations]                                   │
│                                                              │
│   [◀ Prev]                                        [Next ▶]   │
└──────────────────────────────────────────────────────────────┘

Features:

Favorites

Users can save verses for quick access later.

How it works:

Accessing Favorites:

Sync Behavior:

Sharing Verses

Share verses as images for social media or messaging.

How it works:

Reading Mode

Sequential reading for scripture study.

flowchart TD
    A["/read"] -->|Fresh visit| B[Book Cover]
    A -->|Returning user| C[Resume Position]
    B -->|Begin Journey| D[Chapter 1 Intro]
    C -->|URL updated| E[Chapter Intro]
    D --> F[Verse 1]
    E --> G[Resume Verse]
    F -->|Swipe/Key| H[Next Verse]
    G -->|Swipe/Key| H
    H -->|Chapter end| I[Next Chapter Intro]
    I --> J[Continue...]

Design Philosophy:

Screen States:

State Display Action
Book Cover Title, tagline, “Begin Journey” Tap CTA or swipe
Chapter Intro Chapter name, summary, themes Tap CTA or swipe
Verse Focus Sanskrit hero, tap for translation Tap verse or swipe

Navigation:

Input Mobile Desktop
Next Swipe left → or J
Previous Swipe right ← or K
Toggle translation Tap verse Tap verse
Chapter select Bottom nav button Bottom nav button
Font size Bottom nav button (cycles small/medium/large) Same

Persistence:

localStorage
├── geetanjali:readingPosition
│   ├── chapter: number
│   ├── verse: number
│   └── timestamp: ISO8601
├── geetanjali:readingSettings
│   └── fontSize: "small" | "medium" | "large"
├── geetanjali:readingOnboardingSeen
│   └── boolean (first-time tips)
└── geetanjali:favorites
    └── string[] (canonical IDs like "BG_2_47")

User Flow Summary

flowchart TB
    subgraph Discovery["Discovery Journey"]
        H[Homepage] -->|"Explore Verses"| V[Verse Browser]
        V -->|Card click| D[Verse Detail]
        V -->|"Reading Mode" link| R[Reading Mode]
        D -->|Tag click| V
        R -->|Verse link| D
    end

Entry Points:

Technical Notes

API Endpoints:

GET /api/v1/verses                    # List with filters (chapter, featured, principles)
GET /api/v1/verses/count              # Count with same filters
GET /api/v1/verses/{canonical_id}     # Single verse details
GET /api/v1/verses/{id}/translations  # All translations for verse
GET /api/v1/verses/daily              # Daily featured verse
GET /api/v1/reading/book              # Book metadata (title, tagline, intro)
GET /api/v1/reading/chapters/{n}      # Chapter metadata (summary, themes)
GET /api/v1/preferences               # Get user preferences (includes favorites)
PUT /api/v1/preferences               # Update preferences (sync favorites, reading position)

Performance:

Accessibility: