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

# Crossword Puzzle Generator

A full-stack web application for generating and solving crossword puzzles with various topics.

## Features

- Topic-based crossword generation
- Interactive puzzle grid with proper visual formatting
- Clues display (Across and Down)
- Solution reveal functionality
- Responsive design

## Prerequisites

- Node.js (v14 or higher)
- npm

## Installation & Setup

1. **Clone the repository**
   ```bash
   git clone <your-repo-url>
   cd cross-words
   ```

2. **Install backend dependencies**
   ```bash
   cd crossword-app/backend
   npm install
   ```

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

## Running the Application

### Development Mode

1. **Start the backend server**
   ```bash
   cd crossword-app/backend
   npm run dev
   ```
   The backend will run on `http://localhost:3001`

2. **Start the frontend development server** (in a new terminal)
   ```bash
   cd crossword-app/frontend
   npm run dev
   ```
   The frontend will run on `http://localhost:5173`

3. **Open your browser** and navigate to `http://localhost:5173`

### Docker Deployment

**Build and run with Docker:**
```bash
# From project root
docker build -t crossword-app .
docker run -p 7860:7860 -e NODE_ENV=production crossword-app
```

Open `http://localhost:7860` to access the application.

**For Hugging Face Spaces:** This repository is ready for Docker-based deployment.

## How to Use

1. Select one or more topics from the available options
2. Click "Generate Puzzle" to create a new crossword
3. Fill in the grid using the provided clues
4. Click "Reveal Solution" to see the answers
5. Click "Reset" to clear the grid and start over

## Project Structure

```
cross-words/
├── crossword-app/
│   ├── backend/          # Node.js/Express API
│   │   ├── src/
│   │   ├── package.json
│   │   └── ...
│   └── frontend/         # React application
│       ├── src/
│       ├── package.json
│       └── ...
├── crossword.py          # Original Python implementation
└── README.md
```

## Technology Stack

- **Frontend**: React, Vite, CSS
- **Backend**: Node.js, Express
- **Algorithm**: Backtracking-based crossword generation
- **Deployment**: Docker (ready for Hugging Face Spaces)

## Documentation

For detailed technical documentation, deployment guides, and API specifications, see the [crossword-app README](./crossword-app/README.md).