CLAUDE.md

CLAUDE.md

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

Project Structure

This is a full-stack crossword puzzle generator with two backend implementations:

• Node.js Backend (backend/) - Original implementation with static word lists
• Python Backend (backend-py/) - New implementation with AI-powered vector search
• React Frontend (frontend/) - Modern React app with Vite

Current deployment uses the Python backend with Docker containerization.

Development Commands

Frontend Development

cd frontend
npm install
npm run dev          # Start development server on http://localhost:5173
npm run build        # Build for production
npm run preview      # Preview production build

Backend Development (Python - Primary)

cd backend-py

# Testing
python run_tests.py                                    # Run all tests
python run_tests.py crossword_generator_fixed         # Run specific test
pytest tests/ -v                                      # Direct pytest
pytest tests/test_index_bug_fix.py -v                 # Core functionality tests
python test_local.py                                  # Quick test without ML deps

# Development server
python app.py                                         # Start FastAPI server on port 7860

# Debug/development tools
python test_simple_generation.py                      # Test crossword generation
python debug_grid_direct.py                          # Debug grid placement

Backend Development (Node.js - Legacy)

cd backend
npm install
npm run dev          # Start Express server on http://localhost:3000
npm test             # Run tests

Docker Deployment

# Build and run locally
docker build -t crossword-app .
docker run -p 7860:7860 -e NODE_ENV=production crossword-app

# Test deployment
curl http://localhost:7860/api/topics
curl http://localhost:7860/health

Linting and Type Checking

# Python backend
cd backend-py
mypy src/           # Type checking (if mypy installed)
ruff src/           # Linting (if ruff installed)

# Frontend
cd frontend
npm run lint        # ESLint (if configured)

Architecture Overview

Full-Stack Components

Frontend (frontend/)

• React 18 with hooks and functional components
• Key components: TopicSelector.jsx, PuzzleGrid.jsx, ClueList.jsx
• Custom hook: useCrossword.js manages puzzle state
• Grid rendering using CSS Grid with interactive cell filling

Python Backend (backend-py/ - Primary)

• FastAPI web framework serving both API and static frontend files
• AI-powered word generation using vector similarity search
• Comprehensive bounds checking fixes for crossword generation
• Multi-layer caching system with graceful fallback to static words

Node.js Backend (backend/ - Legacy)

• Express.js with file-based word storage
• Original crossword generation algorithm
• Static word lists organized by topic (animals.json, science.json, etc.)

Core Python Backend Components

CrosswordGeneratorFixed (backend-py/src/services/crossword_generator_fixed.py)

• Main crossword generation algorithm using backtracking
• Handles grid placement, bounds checking, and word intersections
• Contains fixes for "list index out of range" errors with comprehensive bounds validation
• Key methods: _create_grid(), _backtrack_placement(), _can_place_word(), _place_word()

VectorSearchService (backend-py/src/services/vector_search.py)

• AI-powered word discovery using sentence-transformers + FAISS
• Extracts 30K+ words from model vocabulary vs static word lists
• Implements semantic similarity search with caching and fallback systems
• Requires torch/sentence-transformers dependencies (optional for core functionality)

WordCache (backend-py/src/services/word_cache.py)

• Multi-layer caching system for vector-discovered words
• Handles permission issues with fallback mechanisms
• Reduces dependency on static word files

Data Flow

1. User Interaction → React frontend (TopicSelector, PuzzleGrid)
2. API Request → FastAPI backend (backend-py/routes/api.py)
3. Word Selection → VectorSearchService (AI) or static word fallback
4. Grid Generation → CrosswordGeneratorFixed backtracking algorithm
5. Response → JSON with grid, clues, and metadata
6. Frontend Rendering → Interactive crossword grid with clues

Critical Dependencies

Frontend:

• React 18, Vite (development/build)
• Node.js 18+ and npm 9+

Python Backend (Primary):

• FastAPI, uvicorn, pydantic (web framework)
• pytest, pytest-asyncio (testing)

Optional AI Features:

• torch, sentence-transformers, faiss-cpu (vector search)
• httpx (for API testing)

Node.js Backend (Legacy):

• Express.js, cors, helmet
• JSON file-based word storage

The Python backend gracefully degrades to static word lists when AI dependencies are missing.

API Endpoints

Both backends provide compatible REST APIs:

• GET /api/topics - Get available topics
• POST /api/generate - Generate crossword puzzle
• POST /api/validate - Validate user answers
• GET /api/health - Health check

Testing Strategy

Python Backend Tests:

• test_crossword_generator_fixed.py - Grid generation logic
• test_index_bug_fix.py - Bounds checking and index error fixes (CRITICAL)
• test_vector_search.py - AI word generation (needs torch)
• test_api_routes.py - FastAPI endpoints (needs httpx)

Frontend Tests:

• Component testing with React Testing Library (if configured)
• E2E testing with Playwright/Cypress (if configured)

Key Fixes Applied

Index Error Resolution:

• Added comprehensive bounds checking in _can_place_word(), _place_word(), _remove_word()
• Fixed _calculate_placement_score() to validate grid coordinates before access
• All grid access operations now validate row/col bounds

Word Boundary Issues:

• 2-letter sequences at crossword intersections are normal behavior, not bugs
• Removed overly strict validation that was rejecting valid crossword patterns
• Grid placement logic maintains compatibility with JavaScript backend quality

Environment Configuration

Python Backend (Production):

NODE_ENV=production
PORT=7860
EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2
WORD_SIMILARITY_THRESHOLD=0.65
PYTHONPATH=/app/backend-py
PYTHONUNBUFFERED=1

Frontend Development:

VITE_API_BASE_URL=http://localhost:7860  # Points to Python backend

Node.js Backend (Legacy):

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:pass@host:port/db  # Optional

Performance Notes

Python Backend:

• Startup: ~30-60 seconds with AI (model download), ~2 seconds without
• Memory: ~500MB-1GB with AI, ~100MB without
• Response Time: ~200-500ms with vector search, ~100ms with static words
• FAISS index building is the main startup bottleneck

Frontend:

• Development: Hot reload with Vite (~200ms)
• Build Time: ~10-30 seconds for production build
• Bundle Size: Optimized with Vite tree-shaking

Deployment:

• Docker build time: ~5-10 minutes (includes frontend build + Python deps)
• Container size: ~1.5GB (includes ML models and dependencies)
• Hugging Face Spaces deployment: Automatic on git push
• run unit tests after fixing a bug
• do not use any static files for any word generation or clue gebneration.
• we do not prefer inference api based solution