bibdle/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Bibdle is a daily Bible verse guessing game built with SvelteKit 5. Players read a verse and try to guess which book of the Bible it comes from. The game provides feedback hints (Testament match, Section match, Adjacent book) similar to Wordle-style games. Progress is stored locally in the browser and a new verse is generated daily.

Tech Stack

• Framework: SvelteKit 5 with Svelte 5 (uses runes: $state, $derived, $effect, $props)
• Styling: Tailwind CSS 4
• Database: SQLite with Drizzle ORM
• Auth: Session-based authentication using @oslojs/crypto (SHA-256 hashed tokens)
• Deployment: Node.js adapter for production builds
• External API: bible-api.com for fetching random verses

Development Commands

# Start development server
npm run dev

# Type checking
npm run check
npm run check:watch

# Build for production
npm run build

# Preview production build
npm run preview

# Database operations
npm run db:push      # Push schema changes to database
npm run db:generate  # Generate migrations
npm run db:migrate   # Run migrations
npm run db:studio    # Open Drizzle Studio GUI

Architecture

Database Schema (src/lib/server/db/schema.ts)

• user: User accounts with id and age
• session: Auth sessions linked to users with expiration timestamps
• daily_verses: Cached daily verses with book ID, verse text, reference, and date

Sessions expire after 30 days and are automatically renewed when less than 15 days remain.

Bible Data (src/lib/types/bible.ts)

The bibleBooks array contains all 66 Bible books with metadata:

• Testament (old/new)
• Section (Law, History, Wisdom, Prophets, Gospels, Epistles, Apocalyptic)
• Order (1-66, used for adjacency detection)
• Popularity (2-10, affects grading - higher is more popular)

Daily Verse System (src/routes/+page.server.ts)

The getTodayVerse() function:

1. Checks database for existing verse for today's date
2. If none exists, fetches from bible-api.com (random verse + 2 consecutive verses)
3. Caches in database with UTC date key
4. Returns verse with book metadata for the game

Game Logic (src/routes/+page.svelte)

State Management:

• guesses array stores game state in localStorage keyed by date
• Each guess tracks: book, testamentMatch, sectionMatch, adjacent
• isWon is derived from whether any guess matches the correct book

Grading System:

// Grade formula combines performance + difficulty
performanceScore = max(0, 10 - numGuesses)
difficulty = 14 - popularity
totalScore = performanceScore + difficulty * 0.8

// S: 14+, A: 11+, B: 8+, C: 5+, C-: <5

Hint System:

• ✅ Green checkmark: Exact match
• 🟩 Green square: Section matches
• 🟧 Orange square: Testament matches (shared results)
• ‼️ Double exclamation: Adjacent book in Bible order
• 🟥 Red square: No match

Authentication System (src/lib/server/auth.ts)

• Token-based sessions with SHA-256 hashing
• Cookies store session tokens, validated on each request
• Hook in src/hooks.server.ts populates event.locals.user and event.locals.session
• Note: Currently the schema includes user table but auth UI is not yet implemented

Key Files

• src/routes/+page.svelte - Main game UI and client-side logic
• src/routes/+page.server.ts - Server load function, fetches/caches daily verse
• src/lib/server/bible-api.ts - External API integration for verse fetching
• src/lib/server/bible.ts - Bible book utility functions
• src/lib/types/bible.ts - Bible books data and TypeScript types
• src/lib/server/db/schema.ts - Drizzle ORM schema definitions
• src/hooks.server.ts - SvelteKit server hook for session validation

Environment Variables

Required in .env:

• DATABASE_URL - Path to SQLite database file (e.g., ./local.db)

Deployment

The project uses @sveltejs/adapter-node for deployment. The build output is a Node.js server that can be run with systemd or similar process managers. See bibdle.service and bibdle.socket for systemd configuration.

Important Notes

• Uses Svelte 5 runes syntax ($state, $derived, $effect, $props) - not stores or reactive declarations
• The schema includes authentication tables but the login/signup UI is not yet implemented
• Daily verses are cached permanently in the database to ensure consistency
• LocalStorage persists guesses per day using the key pattern bibdle-guesses-${date}
• The game validates book IDs from the API against the hardcoded bibleBooks array