README.md

metadata

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

   git clone <your-repo-url>
   cd cross-words
   

2. Install backend dependencies

   cd crossword-app/backend
   npm install
   

3. Install frontend dependencies

   cd ../frontend
   npm install
   

Running the Application

Development Mode

1. Start the backend server

   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)

   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:

# 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.