crossword-app/README.md

---
title: Crossword Puzzle Generator
emoji: 🧩
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# Crossword Puzzle Generator

A full-stack web application that generates custom crossword puzzles based on selected topics using React frontend and Node.js backend.

## Features

- **Topic Selection**: Choose from various categories (Animals, Science, Geography, Technology)
- **Dynamic Grid Generation**: Automatically creates crossword grids with word intersections
- **Interactive Interface**: Click-to-fill crossword grid with real-time validation
- **Difficulty Levels**: Easy, Medium, and Hard puzzle generation
- **Responsive Design**: Works on desktop and mobile devices

## Tech Stack

### Frontend
- **React 18** with hooks and functional components
- **Vite** for fast development and building
- **CSS Grid** for puzzle layout
- **Vanilla CSS** for styling (no external UI libraries)

### Backend
- **Node.js** with Express.js framework
- **File-based word storage** (JSON files by topic)
- **CORS** enabled for cross-origin requests
- **Rate limiting** for API protection
- **Helmet** for security headers

### Database (Optional)
- **PostgreSQL** schema included for advanced features
- **Migration and seed scripts** provided
- Currently uses JSON files for simplicity

## Project Structure

```
crossword-app/
├── frontend/                 # React frontend application
│   ├── src/
│   │   ├── components/      # React components
│   │   │   ├── TopicSelector.jsx
│   │   │   ├── PuzzleGrid.jsx
│   │   │   ├── ClueList.jsx
│   │   │   └── LoadingSpinner.jsx
│   │   ├── hooks/           # Custom React hooks
│   │   │   └── useCrossword.js
│   │   ├── utils/           # Utility functions
│   │   │   └── gridHelpers.js
│   │   ├── styles/          # CSS styling
│   │   │   └── puzzle.css
│   │   ├── App.jsx          # Main app component
│   │   └── main.jsx         # React entry point
│   ├── public/              # Static assets
│   ├── package.json
│   └── vite.config.js
├── backend/                 # Node.js backend API
│   ├── src/
│   │   ├── controllers/     # Request handlers
│   │   │   └── puzzleController.js
│   │   ├── services/        # Business logic
│   │   │   ├── crosswordGenerator.js
│   │   │   └── wordService.js
│   │   ├── models/          # Data models
│   │   │   ├── Word.js
│   │   │   └── Topic.js
│   │   ├── routes/          # API routes
│   │   │   └── api.js
│   │   └── app.js           # Express application
│   ├── data/
│   │   └── word-lists/      # JSON word files by topic
│   ├── package.json
│   └── .env                 # Environment variables
└── database/                # Database schema (optional)
    ├── migrations/
    └── seeds/
```

## Getting Started

### Prerequisites
- Node.js 18+ and npm 9+
- PostgreSQL (optional, for advanced features)

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd crossword-app
   ```

2. **Install backend dependencies**
   ```bash
   cd backend
   npm install
   ```

3. **Install frontend dependencies**
   ```bash
   cd ../frontend
   npm install
   ```

4. **Configure environment variables**
   ```bash
   cd ../backend
   cp .env.example .env
   # Edit .env with your configuration
   ```

### Development

1. **Start the backend server**
   ```bash
   cd backend
   npm run dev
   ```
   Backend runs on http://localhost:3000

2. **Start the frontend development server**
   ```bash
   cd frontend
   npm run dev
   ```
   Frontend runs on http://localhost:5173

3. **Access the application**
   Open http://localhost:5173 in your browser

### API Endpoints

- `GET /api/topics` - Get available topics
- `POST /api/generate` - Generate a crossword puzzle
- `POST /api/validate` - Validate user answers
- `GET /api/words/:topic` - Get words for a topic (admin)
- `GET /api/health` - Health check

### Example API Usage

**Generate a puzzle:**
```bash
curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "topics": ["animals", "science"],
    "difficulty": "medium"
  }'
```

## Algorithm Details

### Crossword Generation Process

1. **Word Selection**: Picks 6-12 words from selected topics based on difficulty
2. **Grid Sizing**: Automatically calculates optimal grid size
3. **Placement Algorithm**: Uses backtracking to place words with intersections
4. **Validation**: Ensures valid crossword structure with proper letter matching

### Core Algorithm Features

- **Backtracking**: Tries all possible word placements and backtracks on conflicts
- **Intersection Logic**: Words can only cross where letters match
- **Grid Optimization**: Minimizes grid size while maximizing word density
- **Difficulty Scaling**: Adjusts word length and complexity based on difficulty

## Deployment

### Docker (Hugging Face Spaces/Local)

**Build and run locally:**
```bash
# Build the Docker image
docker build -t crossword-app .

# Run the container (production mode)
docker run -p 7860:7860 -e NODE_ENV=production crossword-app

# Or run in background
docker run -d -p 7860:7860 -e NODE_ENV=production --name crossword-app crossword-app
```

**Test the deployment:**
```bash
# Test API endpoint
curl http://localhost:7860/api/topics

# Test frontend (should return HTML)
curl http://localhost:7860/

# View container logs
docker logs crossword-app

# Stop and cleanup
docker stop crossword-app && docker rm crossword-app
```

The app will be available at http://localhost:7860

**For Hugging Face Spaces:**
1. Create a new Space with "Docker" SDK
2. Upload the entire `crossword-app/` directory
3. The container will build automatically and deploy on port 7860

### Frontend (Vercel/Netlify)
```bash
cd frontend
npm run build
# Deploy dist/ folder to your hosting service
```

### Backend (Railway/Heroku)
```bash
cd backend
# Set environment variables in your hosting service
# Deploy with git or Docker
```

### Environment Variables for Production
```bash
NODE_ENV=production
PORT=7860
DATABASE_URL=postgresql://user:pass@host:port/db (optional)
CORS_ORIGIN=https://your-frontend-domain.com (for separate deployments)
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Future Enhancements

- [ ] User accounts and saved puzzles
- [ ] Puzzle sharing and social features
- [ ] Advanced word filtering and custom topics
- [ ] Print-friendly puzzle format
- [ ] Mobile app versions
- [ ] Multiplayer crossword solving
- [ ] AI-generated clues

## License

This project is licensed under the MIT License - see the LICENSE file for details.