mirror of
https://github.com/kennethreitz/kjvstudy.org.git
synced 2026-06-05 23:00:16 +00:00
kennethreitz
8322a88edd
- Extracted ~1250 lines of JavaScript from base.html to static/base.js - Reduced base.html from ~2700 lines to ~1440 lines - Updated tests to expect 404 (not 500) for invalid resources - Updated CLAUDE.md to reflect proper error handling 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
252 lines
7.1 KiB
Markdown
252 lines
7.1 KiB
Markdown
# 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 **100 comprehensive tests** with **100% pass rate**:
|
|
|
|
- **25 API endpoint tests** (`test_api.py`)
|
|
- Health checks
|
|
- Verse endpoints (single, range, verse of the day)
|
|
- Book endpoints (list, details, chapters, full text)
|
|
- Bible endpoint (entire Bible)
|
|
- Search functionality
|
|
- Interlinear data (Hebrew/Greek)
|
|
- Cross-references
|
|
- Topics and reading plans
|
|
|
|
- **60 edge case tests** (`test_edge_cases.py`)
|
|
- Error handling (invalid inputs)
|
|
- Verse range edge cases
|
|
- Book abbreviations
|
|
- Book boundaries (shortest, longest, etc.)
|
|
- Search functionality edge cases
|
|
- Content validation
|
|
- Performance tests with large datasets
|
|
|
|
- **15 web route tests** (`test_web_routes.py`)
|
|
- Homepage and navigation
|
|
- Book pages
|
|
- Chapter and verse pages
|
|
- Search pages
|
|
- Topics and reading plans
|
|
- HTML structure and accessibility
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
## Contributing
|
|
|
|
When making changes:
|
|
|
|
1. **Write tests** for new features
|
|
2. **Run tests** before committing: `uv run pytest tests/ -v`
|
|
3. **Check CI** - GitHub Actions will run tests automatically
|
|
4. **Update docs** if adding API endpoints
|
|
5. **Follow existing patterns** in the codebase
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# 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
|
|
|
|
# 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
|