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, etc.) similar to Wordle-style games. Progress is stored locally in the browser and a new verse is generated daily.

You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:

(Make sure you use the Svelte agent to execute these commands)

Available MCP Tools:

1. list-sections

Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths. When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.

2. get-documentation

Retrieves full documentation content for specific sections. Accepts single or multiple sections. After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.

3. svelte-autofixer

Analyzes Svelte code and returns issues and suggestions. You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.

4. playground-link

Generates a Svelte Playground link with the provided code. After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.

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
bun run dev

# Type checking
bun run check
bun run check:watch

# Build for production
bun run build

# Preview production build
bun run preview

# Database operations
bun run db:push      # Push schema changes to database
bun run db:generate  # Generate migrations (DO NOT RUN)
bun run db:migrate   # Run migrations (DO NOT RUN)
bun 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