crossword-app/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 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

   git clone <repository-url>
   cd crossword-app
   

2. Install backend dependencies

   cd backend
   npm install
   

3. Install frontend dependencies

   cd ../frontend
   npm install
   

4. Configure environment variables

   cd ../backend
   cp .env.example .env
   # Edit .env with your configuration
   

Development

1. Start the backend server

   cd backend
   npm run dev
   

   Backend runs on http://localhost:3000

2. Start the frontend development server

   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:

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:

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

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

cd frontend
npm run build
# Deploy dist/ folder to your hosting service

Backend (Railway/Heroku)

cd backend
# Set environment variables in your hosting service
# Deploy with git or Docker

Environment Variables for Production

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.