kjvstudy.org/CLAUDE.md

Claude Code Development Notes

This file contains information for Claude Code (AI assistant) about the kjvstudy.org project.

Project Overview

KJV Study is a modern web application for studying the King James Bible with AI-powered commentary and insights. Built with FastAPI, it provides both a web interface and a comprehensive RESTful API.

Tech Stack

• Backend: FastAPI (Python 3.13)
• Package Manager: uv
• Bible Data: Custom implementation with local JSON (31,102 verses from 1769 Cambridge KJV)
• Templates: Jinja2
• Styling: Tufte CSS (Edward Tufte-inspired typography)
• Deployment: Fly.io
• CI/CD: GitHub Actions

Testing

Test Suite

The project has 941 comprehensive tests across 16 test files:

• 87 API endpoint tests (test_api.py) - Health checks, verse/book/Bible endpoints, search, interlinear, cross-references, topics, reading plans
• 87 utility tests (test_utils.py) - Helper functions and utilities
• 85 coverage tests part 5 (test_coverage_part5.py)
• 84 coverage tests part 6 (test_coverage_part6.py)
• 77 coverage tests part 2 (test_coverage_part2.py)
• 77 coverage improvement tests (test_coverage_improvements.py)
• 76 resource route tests (test_resource_routes.py) - Biblical resources, parables, names of God, etc.
• 64 web route tests (test_web_routes.py) - Homepage, book/chapter/verse pages, search, topics, accessibility
• 62 Strong's concordance tests (test_strongs.py) - Hebrew/Greek lexicon functionality
• 61 coverage tests part 4 (test_coverage_part4.py)
• 59 coverage tests part 3 (test_coverage_part3.py)
• 46 advanced route tests (test_advanced_routes.py) - Commentary, stories, family trees, etc.
• 39 edge case tests (test_edge_cases.py) - Error handling, boundary conditions, validation
• 22 data validation tests (test_data_validation.py) - JSON data integrity
• 14 sitemap/utility tests (test_sitemap_and_utilities.py)
• 1 KJV core test (test_kjv.py)

Running Tests

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_api.py -v

# Run with coverage
uv run pytest tests/ --cov=kjvstudy_org --cov-report=html

# Run in Docker (recommended)
docker compose exec web uv run pytest tests/ -v

Test Fixtures

Shared fixtures are defined in tests/conftest.py:

• client - FastAPI TestClient
• sample_verses - Common verse references
• sample_books - Sample book names
• book_abbreviations - Abbreviation mappings
• bible_facts - Bible validation data

CI/CD

Tests run automatically via GitHub Actions:

• On every push to main
• On every pull request
• Before deployment to Fly.io

See .github/workflows/test.yml and .github/workflows/fly-deploy.yml

API Documentation

The API is fully documented with OpenAPI/Swagger:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI JSON: http://localhost:8000/api/openapi.json

Key API Endpoints

GET /api/health                              - Health check
GET /api/verse/{book}/{chapter}/{verse}      - Get single verse
GET /api/verse-range/{book}/{chapter}/{start}/{end} - Get verse range
GET /api/verse-of-the-day                    - Get daily verse
GET /api/books                               - List all books
GET /api/books/{book}                        - Get book details
GET /api/books/{book}/chapters/{chapter}     - Get chapter
GET /api/books/{book}/text                   - Get entire book
GET /api/bible                               - Get entire Bible (31,102 verses)
GET /api/search?q={query}                    - Search verses
GET /api/interlinear/{book}/{chapter}/{verse} - Get word-by-word analysis
GET /api/cross-references/{book}/{chapter}/{verse} - Get cross-references
GET /api/topics                              - List topics
GET /api/topics/{topic_name}                 - Get topic details
GET /api/reading-plans                       - List reading plans
GET /api/reading-plans/{plan_id}             - Get reading plan

All endpoints support book name abbreviations (Gen, Ex, Mt, etc.)

Development Workflow

Local Development

# Install dependencies
uv sync

# Run development server
uv run uvicorn kjvstudy_org.server:app --reload

# Or use Docker
docker compose up

Project Structure

kjvstudy_org/
├── server.py           # FastAPI application
├── kjv.py             # Bible data access
├── cross_references.py # Cross-reference data
├── reading_plans.py    # Reading plan data
├── topics.py          # Topical index
├── interlinear_loader.py # Hebrew/Greek word analysis
├── templates/         # Jinja2 HTML templates
└── static/            # CSS, images, etc.

tests/
├── conftest.py        # Shared fixtures
├── test_api.py        # API tests
├── test_edge_cases.py # Edge case tests
├── test_web_routes.py # Web route tests
└── README.md          # Test documentation

Key Features

1. Comprehensive Bible Text

   • All 66 books, 31,102 verses
   • Book abbreviation support
   • Chapter and verse navigation

2. Study Resources

   • Cross-references
   • Topical index
   • Reading plans
   • Study guides
   • Biblical timeline
   • Family trees/genealogies
   • Maps

3. Advanced Features

   • Interlinear data (Hebrew/Greek)
   • Word-by-word analysis
   • Strong's numbers
   • Full-text search
   • Verse of the day

4. API

   • RESTful JSON API
   • OpenAPI documentation
   • Example parameters
   • Comprehensive endpoints

Code Quality

Warnings (Known Issues)

The test suite shows several deprecation warnings:

1. example deprecated in favor of examples

   • FastAPI parameter examples should use examples= instead of example=
   • Non-breaking, cosmetic issue

2. on_event deprecated in favor of lifespan

   • FastAPI startup events should use lifespan context manager
   • Non-breaking, will be fixed in future update

3. TemplateResponse parameter order

   • Starlette expects Request as first parameter
   • Non-breaking, cosmetic issue

None of these warnings affect functionality.

Data Validation

Always validate data before committing changes to JSON files:

# Validate all data files with Pydantic models
uv run python scripts/validate_data.py

This validates:

• bible_metadata.json
• featured_verses.json
• reading_plans/ (12 files)
• red_letter_verses.json
• resource_slugs.json
• study_guides/ (36 files)
• topics/ (36 files)
• verse_commentary/ (66 files - one per book)
• word_studies.json

Contributing

When making changes:

1. Write tests for new features
2. Run tests before committing: uv run pytest tests/ -v
3. Validate data before committing: uv run python scripts/validate_data.py
4. Check CI - GitHub Actions will run tests automatically
5. Update docs if adding API endpoints
6. Follow existing patterns in the codebase

Useful Commands

# Sync dependencies
uv sync

# Run server
uv run uvicorn kjvstudy_org.server:app --reload

# Run tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_api.py::TestAPIHealth -v

# Check test coverage
uv run pytest tests/ --cov=kjvstudy_org --cov-report=term-missing

# Validate data files
uv run python scripts/validate_data.py

# Format code (if ruff is configured)
uv run ruff check .

# Docker commands
docker compose up            # Start server
docker compose exec web bash # Shell into container
docker compose exec web uv run pytest tests/ -v # Run tests in container

Notes for Claude

• All tests pass (100/100)
• Use uv for all Python package management
• API responses use name field for books, not book
• API responses use start/end for verse ranges, not start_verse/end_verse
• Error handling returns proper 404 for invalid inputs (not found resources)
• Book abbreviations are comprehensive but some edge cases may not work
• The project uses Tufte CSS for clean, readable typography
• Interlinear data is available for most verses but not all
• Cross-references data is extensive but not complete for all verses