Skip to main content

Knowledge > Processes > Illustration Browse Flow

Illustration Browse Flow

This document describes how a pastor discovers, browses, and uses sermon illustrations on IllustrateTheWord (illustratetheword.com).

Overview​

illustratetheword.com
        │
        ├── /illustrations ──> Browse grid (filter, sort, paginate)
        │         │
        │    click a card
        │         │
        │   /illustrations/[slug] ──> Detail page
        │         │
        │    ┌────┴────────────────────────────┐
        │    │                                  │
        │  public / free_signup              premium
        │  (full content visible)       (teaser + paywall)
        │         │                            │
        │    Copy, Share, Favorite        "Unlock Premium"
        │    Add to Collection             $9.95/mo CTA
        │    Personalize
        │
        ├── /search?scripture=... ──> Scripture-specific results
        ├── /topics/[slug] ──> Topic-specific results
        ├── /browse/[type] ──> Content type results
        └── /emotions/[slug] ──> Emotion-specific results

Step 1: Arriving at the Browse Page​

A pastor visits illustratetheword.com/illustrations (or navigates from the homepage).

The browse page displays:

  1. Hero section -- shows total illustration count (50,000+), title, and subtitle.
  2. Search bar -- full-text search input at the top.
  3. Content type filter pills -- "All", then the first 8 content types as clickable pills, plus "All types" link to /browse.
  4. Sort and source filters -- "Top Rated" (default), "Newest", "Oldest" sort options; "All Sources" or specific featured authors (Biblical Illustrator, Spurgeon, Maclaren).
  5. Results grid -- 24 illustrations per page in a 3-column responsive grid.
  6. Pagination -- Previous/Next links with page count.

Full-Text Search​

  1. Pastor types a keyword or phrase in the search bar.
  2. The search uses PostgreSQL full-text search on the search_vector tsvector column.
  3. This searches across both content and title fields.
  4. Search is combined with any active filters.

Content Type Filter​

26 content types are available, including:

  • sermon_illustration, historical_illustration, poetry_illustration
  • biblical_insight, story, quote, movie_analogy, devotional
  • lens_perspective, application_point, theological_reflection
  • show_dont_tell_prompt, vivid_retelling, character_profile
  • prayer, spiritual_discipline, tv_analogy, and more.

Clicking a content type pill either:

  • Links to /browse/{type-slug} (for types with dedicated slug pages), OR
  • Adds ?type={value} to the illustrations URL.

Topic Filter​

  • Available via /topics/{slug} pages.
  • Uses the topics array column with @> (contains) operator.
  • Topics are stored lowercase in the database.

Scripture Reference Filter​

  • Available via /search?scripture={ref} pages.
  • When scripture is the ONLY active filter, uses a specialized RPC for partial matching (e.g., "Genesis 2:15-17" also finds all Genesis 2 illustrations).
  • When combined with other filters, uses exact array contains as fallback.

Theological Tradition (Lens) Filter​

  • Available via ?tradition={lens_id} parameter.
  • Matches illustrations by their theological_lens_id.
  • Also includes universal illustrations (is_universal = true) in results.
  • 17 traditions: Reformed, Catholic, Lutheran, Anglican, Methodist, Baptist, Pentecostal, Orthodox, Anabaptist, Wesleyan, Evangelical, Charismatic, Liberation, Feminist, Black Church, Emergent, Dispensationalist.

Emotion Filter​

  • Available via /emotions/{slug} pages.
  • Uses the emotions array column with contains operator.

Author/Source Filter​

  • Featured authors available as filter pills on the browse page.
  • Filters by primary_author exact match.
  • Three featured: "Joseph S. Exell" (Biblical Illustrator), "Charles H. Spurgeon", "Alexander Maclaren".

Sort Options​

SortBehavior
Top Rated (default)quality_score descending -- highest quality first
Newestcreated_at descending -- most recently added first
Oldestcreated_at ascending -- oldest first

Step 3: How the Search Query Executes​

The searchIllustrations() function queries the dir_illustrations view:

  1. Select card display fields with exact count for pagination.
  2. Apply active filters (text search, content type, topic, emotion, doctrine, audience, author, tradition, scripture).
  3. Apply sort order.
  4. Paginate with .range(from, to) -- 24 results per page.
  5. Return { data, total, total_pages }.

The dir_illustrations View​

  • A read-only SQL view (not materialized) — always reflects live data from unified_rag_content.
  • No refresh needed — content appears immediately when inserted/updated.
  • Sources from unified_rag_content (327K records in the public schema).
  • Includes 26 content types with derived columns: slug, teaser, visibility_tier.
  • Includes structured data: application_points, sermon_sections, spiritual_disciplines, creative_approach.

Step 4: Illustration Card Display​

Each IllustrationCard in the grid shows:

  • Title of the illustration.
  • Content type badge with emoji icon (e.g., movie reel for movie_analogy).
  • Teaser text -- a short preview of the content (falls back to summary if teaser matches title).
  • Primary topic/theme tags.
  • Scripture reference (if available).
  • Author and source attribution.
  • AI-generated badge (if source_type = 'ai_generated').
  • "Surprise Me" button -- available in the filter bar to jump to a random illustration.

Step 5: Illustration Detail Page (/illustrations/[slug])​

When a pastor clicks an illustration card:

  1. Fetch the illustration from dir_illustrations by slug.
  2. Fetch related content in parallel:
    • Related illustrations (by topic/theme similarity, up to 6).
    • More illustrations for the same scripture passage (up to 4).
    • LensLines for the same scripture (theological tradition perspectives, up to 17).
  3. Check content gating (see Step 6 below).
  4. Render the detail page:

What the detail page shows:​

  • AI-generated image (if available) with lightbox and attribution caption.
  • Content type label and title.
  • Author/source metadata -- attribution, source type, view count, word count.
  • Full content (if accessible) -- rendered with basic markdown formatting (bold, italic, headers).
  • Action buttons (if content is accessible):
    • Copy -- copies the full illustration text to clipboard.
    • Share -- share via browser share API or link copy.
    • Favorite -- save to user's favorites list.
    • Add to Collection -- organize into custom collections.
    • Personalize -- AI-powered personalization for the pastor's context.
  • Movie/TV info card (for movie_analogy and tv_analogy types only).
  • Tags section:
    • Topics and themes (linked to topic pages).
    • Scripture references (linked to scripture search).
    • Emotional tone tags (linked to emotion pages).
    • Application points (bulleted list).
    • Sermon sections ("Best Used In" -- introduction, body, conclusion, etc.).
    • Spiritual disciplines.
    • Creative approach description.
    • Target audience.
  • LensLines section -- "One Text. Seventeen Voices." Shows how different theological traditions interpret the same passage.
  • More for this passage -- additional illustrations anchored to the same scripture.
  • Related illustrations -- topically similar content.
  • ChurchWiseAI cross-promotion banner.
  • Stock photos -- relevant stock images for sermon slides.

Step 6: Content Gating (Free vs. Premium)​

Every illustration has a visibility_tier assigned by the assign-visibility-tiers.mjs script:

Three Tiers​

Tier~% of LibraryWho Can See Full ContentWhat Is Shown Otherwise
public~18%Everyone (anonymous visitors)Full content, no login required
free_signup~68%Any logged-in user (free account)First 4 paragraphs with gradient fade + "Sign up free" CTA
premium~14%Paid subscribers ($9.95/mo or $99.50/yr)First 4 paragraphs with gradient fade + "Unlock Premium" CTA

What qualifies for each tier:​

  • Public: All historical_illustration content + the top ~50 per non-premium content type (quality score >= 0.75, 100+ words).
  • Free signup: The majority of the library.
  • Premium: movie_analogy, devotional, lens_perspective, application_point, show_dont_tell_prompt, spiritual_discipline, character_profile, vivid_retelling, tv_analogy, plus high-quality sermon_illustration.

How gating is checked at runtime:​

  1. The detail page is a dynamic server component (force-dynamic).
  2. Get the current user from Supabase Auth: supabase.auth.getUser().
  3. Determine access:
    • IF visibility_tier = 'public' --> full access (no login needed).
    • IF visibility_tier = 'free_signup' AND user is logged in --> full access.
    • IF visibility_tier = 'premium' AND user is logged in AND hasActiveSubscription() returns true --> full access.
    • Otherwise --> show teaser with paywall.
  4. hasActiveSubscription() checks the user_subscriptions table for status = 'active' or status = 'trialing'.

Paywall display:​

  • First 4 paragraphs are shown with a gradient fade-out overlay.
  • A prominent card appears with:
    • Lock icon.
    • For not-logged-in users: "Sign up free to read the full illustration" (free_signup) or "Sign up to unlock premium illustrations" (premium).
    • For logged-in non-subscribers: feature list (50,000+ illustrations, movie analogies, 17 traditions, unlimited downloads, weekly new content) + "Unlock Premium -- $9.95/mo" button.
  • Action buttons (copy, collection, personalize) are NOT shown for gated content.
  • Movie/TV info cards are NOT shown (prevents content leak via RSC payload).

Step 7: Saving and Organizing​

Logged-in users can:

Favorites​

  • Click the heart icon on any illustration card or detail page.
  • Saves to user_favorites table (user_id + illustration_id).
  • Favorites are accessible from the user's profile/dashboard.

Collections​

  • Click "Add to Collection" on a detail page.
  • Organize illustrations into named collections for sermon series or topics.

Copy to Clipboard​

  • Click "Copy" to get the full illustration text formatted for pasting into a sermon document.
  • Includes title and scripture reference in the copied text.

Personalize​

  • Click "Personalize" to get an AI-adapted version of the illustration tailored to the pastor's specific context, congregation, or sermon series.

Data Flow Summary​

unified_rag_content (327K rows, public schema)
        │
        │  live SQL view (no refresh needed)
        │
  dir_illustrations (SQL view, ~50K illustration rows)
        │
        │  searchIllustrations() queries this view
        │
  Browse page grid (24 per page)
        │
        │  getIllustrationBySlug() for detail
        │
  Detail page (content gated by visibility_tier + auth state)