display pre-generated crossword

- able to build frontend and backend
- able to display the generated grid
- able to show the words with "Reveal Solution" button

Signed-off-by: Vimal Kumar <[email protected]>

.gitignore

@@ -0,0 +1,42 @@
+# Dependencies
+node_modules/
+*/node_modules/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build outputs
+build/
+dist/
+*/build/
+*/dist/
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

README.md

@@ -0,0 +1,85 @@
+# 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
+
+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`
+
+## 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

crossword-app/README.md

@@ -0,0 +1,209 @@
+# 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
+
+### 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
+DATABASE_URL=postgresql://user:pass@host:port/db
+CORS_ORIGIN=https://your-frontend-domain.com
+JWT_SECRET=your-secure-secret
+```
+
+## 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.

crossword-app/backend/data/word-lists/animals.json

@@ -0,0 +1,27 @@
+[
+  { "word": "DOG", "clue": "Man's best friend" },
+  { "word": "CAT", "clue": "Feline pet that purrs" },
+  { "word": "ELEPHANT", "clue": "Large mammal with a trunk" },
+  { "word": "TIGER", "clue": "Striped big cat" },
+  { "word": "WHALE", "clue": "Largest marine mammal" },
+  { "word": "BUTTERFLY", "clue": "Colorful flying insect" },
+  { "word": "BIRD", "clue": "Flying creature with feathers" },
+  { "word": "FISH", "clue": "Aquatic animal with gills" },
+  { "word": "LION", "clue": "King of the jungle" },
+  { "word": "BEAR", "clue": "Large mammal that hibernates" },
+  { "word": "RABBIT", "clue": "Hopping mammal with long ears" },
+  { "word": "HORSE", "clue": "Riding animal with hooves" },
+  { "word": "SHEEP", "clue": "Woolly farm animal" },
+  { "word": "GOAT", "clue": "Horned farm animal" },
+  { "word": "DUCK", "clue": "Water bird that quacks" },
+  { "word": "CHICKEN", "clue": "Farm bird that lays eggs" },
+  { "word": "SNAKE", "clue": "Slithering reptile" },
+  { "word": "TURTLE", "clue": "Shelled reptile" },
+  { "word": "FROG", "clue": "Amphibian that croaks" },
+  { "word": "SHARK", "clue": "Predatory ocean fish" },
+  { "word": "DOLPHIN", "clue": "Intelligent marine mammal" },
+  { "word": "PENGUIN", "clue": "Flightless Antarctic bird" },
+  { "word": "MONKEY", "clue": "Primate that swings in trees" },
+  { "word": "ZEBRA", "clue": "Striped African animal" },
+  { "word": "GIRAFFE", "clue": "Tallest land animal" }
+]

crossword-app/backend/data/word-lists/geography.json

@@ -0,0 +1,32 @@
+[
+  { "word": "MOUNTAIN", "clue": "High elevation landform" },
+  { "word": "OCEAN", "clue": "Large body of salt water" },
+  { "word": "DESERT", "clue": "Dry, arid region" },
+  { "word": "CONTINENT", "clue": "Large landmass" },
+  { "word": "RIVER", "clue": "Flowing body of water" },
+  { "word": "ISLAND", "clue": "Land surrounded by water" },
+  { "word": "FOREST", "clue": "Dense area of trees" },
+  { "word": "VALLEY", "clue": "Low area between hills" },
+  { "word": "LAKE", "clue": "Body of freshwater" },
+  { "word": "BEACH", "clue": "Sandy shore by water" },
+  { "word": "CLIFF", "clue": "Steep rock face" },
+  { "word": "PLATEAU", "clue": "Elevated flat area" },
+  { "word": "CANYON", "clue": "Deep gorge with steep sides" },
+  { "word": "GLACIER", "clue": "Moving mass of ice" },
+  { "word": "VOLCANO", "clue": "Mountain that erupts" },
+  { "word": "PENINSULA", "clue": "Land surrounded by water on three sides" },
+  { "word": "ARCHIPELAGO", "clue": "Group of islands" },
+  { "word": "PRAIRIE", "clue": "Grassland plain" },
+  { "word": "TUNDRA", "clue": "Cold, treeless region" },
+  { "word": "SAVANNA", "clue": "Tropical grassland" },
+  { "word": "EQUATOR", "clue": "Earth's middle line" },
+  { "word": "LATITUDE", "clue": "Distance from equator" },
+  { "word": "LONGITUDE", "clue": "Distance from prime meridian" },
+  { "word": "CLIMATE", "clue": "Long-term weather pattern" },
+  { "word": "MONSOON", "clue": "Seasonal wind pattern" },
+  { "word": "CAPITAL", "clue": "Main city of country" },
+  { "word": "BORDER", "clue": "Boundary between countries" },
+  { "word": "COAST", "clue": "Land meeting the sea" },
+  { "word": "STRAIT", "clue": "Narrow water passage" },
+  { "word": "DELTA", "clue": "River mouth formation" }
+]

crossword-app/backend/data/word-lists/science.json

@@ -0,0 +1,32 @@
+[
+  { "word": "ATOM", "clue": "Smallest unit of matter" },
+  { "word": "GRAVITY", "clue": "Force that pulls objects down" },
+  { "word": "MOLECULE", "clue": "Group of atoms bonded together" },
+  { "word": "PHOTON", "clue": "Particle of light" },
+  { "word": "CHEMISTRY", "clue": "Study of matter and reactions" },
+  { "word": "PHYSICS", "clue": "Study of matter and energy" },
+  { "word": "BIOLOGY", "clue": "Study of living organisms" },
+  { "word": "ELEMENT", "clue": "Pure chemical substance" },
+  { "word": "OXYGEN", "clue": "Gas essential for breathing" },
+  { "word": "CARBON", "clue": "Element found in all life" },
+  { "word": "HYDROGEN", "clue": "Lightest chemical element" },
+  { "word": "ENERGY", "clue": "Capacity to do work" },
+  { "word": "FORCE", "clue": "Push or pull on an object" },
+  { "word": "VELOCITY", "clue": "Speed with direction" },
+  { "word": "MASS", "clue": "Amount of matter in object" },
+  { "word": "VOLUME", "clue": "Amount of space occupied" },
+  { "word": "DENSITY", "clue": "Mass per unit volume" },
+  { "word": "PRESSURE", "clue": "Force per unit area" },
+  { "word": "TEMPERATURE", "clue": "Measure of heat" },
+  { "word": "ELECTRON", "clue": "Negatively charged particle" },
+  { "word": "PROTON", "clue": "Positively charged particle" },
+  { "word": "NEUTRON", "clue": "Neutral atomic particle" },
+  { "word": "NUCLEUS", "clue": "Center of an atom" },
+  { "word": "CELL", "clue": "Basic unit of life" },
+  { "word": "DNA", "clue": "Genetic blueprint molecule" },
+  { "word": "PROTEIN", "clue": "Complex biological molecule" },
+  { "word": "ENZYME", "clue": "Biological catalyst" },
+  { "word": "VIRUS", "clue": "Infectious agent" },
+  { "word": "BACTERIA", "clue": "Single-celled organisms" },
+  { "word": "EVOLUTION", "clue": "Change in species over time" }
+]

crossword-app/backend/data/word-lists/technology.json

@@ -0,0 +1,32 @@
+[
+  { "word": "COMPUTER", "clue": "Electronic processing device" },
+  { "word": "INTERNET", "clue": "Global computer network" },
+  { "word": "ALGORITHM", "clue": "Set of rules for solving problems" },
+  { "word": "DATABASE", "clue": "Organized collection of data" },
+  { "word": "SOFTWARE", "clue": "Computer programs" },
+  { "word": "HARDWARE", "clue": "Physical computer components" },
+  { "word": "NETWORK", "clue": "Connected system of computers" },
+  { "word": "CODE", "clue": "Programming instructions" },
+  { "word": "ROBOT", "clue": "Automated machine" },
+  { "word": "ARTIFICIAL", "clue": "Made by humans, not natural" },
+  { "word": "DIGITAL", "clue": "Using binary data" },
+  { "word": "BINARY", "clue": "Base-2 number system" },
+  { "word": "PROCESSOR", "clue": "Computer's brain" },
+  { "word": "MEMORY", "clue": "Data storage component" },
+  { "word": "KEYBOARD", "clue": "Input device with keys" },
+  { "word": "MONITOR", "clue": "Computer display screen" },
+  { "word": "MOUSE", "clue": "Pointing input device" },
+  { "word": "PRINTER", "clue": "Device that prints documents" },
+  { "word": "SCANNER", "clue": "Device that digitizes images" },
+  { "word": "CAMERA", "clue": "Device that captures images" },
+  { "word": "SMARTPHONE", "clue": "Portable computing device" },
+  { "word": "TABLET", "clue": "Touchscreen computing device" },
+  { "word": "LAPTOP", "clue": "Portable computer" },
+  { "word": "SERVER", "clue": "Computer that serves data" },
+  { "word": "CLOUD", "clue": "Internet-based computing" },
+  { "word": "WEBSITE", "clue": "Collection of web pages" },
+  { "word": "EMAIL", "clue": "Electronic mail" },
+  { "word": "BROWSER", "clue": "Web navigation software" },
+  { "word": "SEARCH", "clue": "Look for information" },
+  { "word": "DOWNLOAD", "clue": "Transfer data to device" }
+]

crossword-app/backend/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "crossword-backend",
+  "version": "1.0.0",
+  "description": "Node.js backend for crossword puzzle generator",
+  "main": "src/app.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node src/app.js",
+    "dev": "nodemon src/app.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.js\"",
+    "db:migrate": "node scripts/migrate.js",
+    "db:seed": "node scripts/seed.js",
+    "db:reset": "npm run db:migrate && npm run db:seed"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "cors": "^2.8.5",
+    "helmet": "^7.1.0",
+    "express-rate-limit": "^7.1.5",
+    "dotenv": "^16.3.1",
+    "pg": "^8.11.3",
+    "compression": "^1.7.4"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.2",
+    "jest": "^29.7.0",
+    "supertest": "^6.3.3",
+    "eslint": "^8.55.0",
+    "prettier": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
+  "keywords": [
+    "crossword",
+    "puzzle",
+    "word-game",
+    "api",
+    "nodejs",
+    "express"
+  ],
+  "author": "Crossword App Team",
+  "license": "MIT"
+}

crossword-app/backend/src/app.js

@@ -0,0 +1,94 @@
+const express = require('express');
+const cors = require('cors');
+const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+const apiRoutes = require('./routes/api');
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+app.use(helmet());
+
+const corsOptions = {
+  origin: process.env.CORS_ORIGIN || ['http://localhost:5173', 'http://localhost:3000'],
+  credentials: true,
+  optionsSuccessStatus: 200
+};
+app.use(cors(corsOptions));
+
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  message: 'Too many requests from this IP, please try again later.',
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+app.use(limiter);
+
+const generateLimiter = rateLimit({
+  windowMs: 5 * 60 * 1000,
+  max: 10,
+  message: 'Too many puzzle generation requests, please wait before trying again.',
+});
+
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+
+app.use((req, res, next) => {
+  console.log(`${new Date().toISOString()} - ${req.method} ${req.path}`);
+  next();
+});
+
+app.use('/api/generate', generateLimiter);
+app.use('/api', apiRoutes);
+
+app.get('/', (req, res) => {
+  res.json({
+    message: 'Crossword Puzzle API',
+    version: '1.0.0',
+    endpoints: {
+      topics: 'GET /api/topics',
+      generate: 'POST /api/generate',
+      validate: 'POST /api/validate',
+      words: 'GET /api/words/:topic',
+      health: 'GET /api/health'
+    }
+  });
+});
+
+app.use((req, res) => {
+  res.status(404).json({
+    error: 'Not Found',
+    message: `Route ${req.method} ${req.path} not found`,
+    timestamp: new Date().toISOString()
+  });
+});
+
+app.use((error, req, res, next) => {
+  console.error('Error:', error);
+  
+  if (error.type === 'entity.parse.failed') {
+    return res.status(400).json({
+      error: 'Invalid JSON',
+      message: 'Request body contains invalid JSON'
+    });
+  }
+  
+  res.status(500).json({
+    error: 'Internal Server Error',
+    message: process.env.NODE_ENV === 'production' 
+      ? 'Something went wrong' 
+      : error.message,
+    timestamp: new Date().toISOString()
+  });
+});
+
+if (require.main === module) {
+  app.listen(PORT, () => {
+    console.log(`Server running on port ${PORT}`);
+    console.log(`Environment: ${process.env.NODE_ENV || 'development'}`);
+    console.log(`CORS enabled for: ${JSON.stringify(corsOptions.origin)}`);
+  });
+}
+
+module.exports = app;

crossword-app/backend/src/controllers/puzzleController.js

@@ -0,0 +1,65 @@
+const CrosswordGenerator = require('../services/crosswordGenerator');
+const WordService = require('../services/wordService');
+
+class PuzzleController {
+  static async getTopics(req, res) {
+    try {
+      const topics = await WordService.getAllTopics();
+      res.json(topics);
+    } catch (error) {
+      console.error('Error fetching topics:', error);
+      res.status(500).json({ error: 'Failed to fetch topics' });
+    }
+  }
+
+  static async generatePuzzle(req, res) {
+    try {
+      const { topics, difficulty = 'medium' } = req.body;
+      
+      if (!topics || !Array.isArray(topics) || topics.length === 0) {
+        return res.status(400).json({ error: 'Topics array is required' });
+      }
+
+      const generator = new CrosswordGenerator();
+      const puzzle = await generator.generatePuzzle(topics, difficulty);
+      
+      if (!puzzle) {
+        return res.status(400).json({ error: 'Could not generate puzzle with selected topics' });
+      }
+
+      res.json(puzzle);
+    } catch (error) {
+      console.error('Error generating puzzle:', error);
+      res.status(500).json({ error: 'Failed to generate puzzle' });
+    }
+  }
+
+  static async validateAnswers(req, res) {
+    try {
+      const { puzzle, answers } = req.body;
+      
+      if (!puzzle || !answers) {
+        return res.status(400).json({ error: 'Puzzle and answers are required' });
+      }
+
+      const validation = CrosswordGenerator.validateAnswers(puzzle, answers);
+      res.json(validation);
+    } catch (error) {
+      console.error('Error validating answers:', error);
+      res.status(500).json({ error: 'Failed to validate answers' });
+    }
+  }
+
+  static async getWords(req, res) {
+    try {
+      const { topic } = req.params;
+      const words = await WordService.getWordsByTopic(topic);
+      res.json(words);
+    } catch (error) {
+      console.error('Error fetching words:', error);
+      res.status(500).json({ error: 'Failed to fetch words' });
+    }
+  }
+}
+
+module.exports = PuzzleController;

crossword-app/backend/src/models/Topic.js

@@ -0,0 +1,144 @@
+class Topic {
+  constructor({ id, name, description, wordCount = 0, difficulty = 'medium' }) {
+    this.id = id;
+    this.name = name;
+    this.description = description;
+    this.wordCount = wordCount;
+    this.difficulty = difficulty;
+    this.createdAt = new Date();
+    this.updatedAt = new Date();
+  }
+
+  static validateTopic(topicData) {
+    const errors = [];
+    
+    if (!topicData.name || typeof topicData.name !== 'string') {
+      errors.push('Topic name is required and must be a string');
+    } else if (topicData.name.length < 2 || topicData.name.length > 50) {
+      errors.push('Topic name must be between 2 and 50 characters');
+    }
+    
+    if (topicData.description && typeof topicData.description !== 'string') {
+      errors.push('Description must be a string');
+    }
+    
+    if (topicData.difficulty && !['easy', 'medium', 'hard'].includes(topicData.difficulty)) {
+      errors.push('Difficulty must be easy, medium, or hard');
+    }
+    
+    return {
+      isValid: errors.length === 0,
+      errors
+    };
+  }
+
+  static fromJSON(data) {
+    return new Topic(data);
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      wordCount: this.wordCount,
+      difficulty: this.difficulty,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt
+    };
+  }
+
+  updateWordCount(count) {
+    this.wordCount = count;
+    this.updatedAt = new Date();
+  }
+
+  getDisplayName() {
+    return this.name
+      .split(/[-_\s]+/)
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join(' ');
+  }
+
+  getSlug() {
+    return this.name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+  }
+
+  isPopular() {
+    return this.wordCount >= 20;
+  }
+
+  getDifficultyLevel() {
+    const levels = {
+      easy: 1,
+      medium: 2,
+      hard: 3
+    };
+    
+    return levels[this.difficulty] || 2;
+  }
+
+  static getDefaultTopics() {
+    return [
+      new Topic({
+        id: 'animals',
+        name: 'Animals',
+        description: 'Various animals from around the world',
+        wordCount: 25,
+        difficulty: 'easy'
+      }),
+      new Topic({
+        id: 'science',
+        name: 'Science',
+        description: 'Scientific terms and concepts',
+        wordCount: 30,
+        difficulty: 'medium'
+      }),
+      new Topic({
+        id: 'geography',
+        name: 'Geography',
+        description: 'Countries, cities, and geographical features',
+        wordCount: 28,
+        difficulty: 'medium'
+      }),
+      new Topic({
+        id: 'technology',
+        name: 'Technology',
+        description: 'Computer and technology terms',
+        wordCount: 35,
+        difficulty: 'hard'
+      }),
+      new Topic({
+        id: 'history',
+        name: 'History',
+        description: 'Historical events and figures',
+        wordCount: 22,
+        difficulty: 'hard'
+      }),
+      new Topic({
+        id: 'sports',
+        name: 'Sports',
+        description: 'Sports and athletic activities',
+        wordCount: 20,
+        difficulty: 'easy'
+      })
+    ];
+  }
+
+  static sortByDifficulty(topics) {
+    return topics.sort((a, b) => a.getDifficultyLevel() - b.getDifficultyLevel());
+  }
+
+  static sortByPopularity(topics) {
+    return topics.sort((a, b) => b.wordCount - a.wordCount);
+  }
+
+  static filterByDifficulty(topics, difficulty) {
+    return topics.filter(topic => topic.difficulty === difficulty);
+  }
+}
+
+module.exports = Topic;

crossword-app/backend/src/models/Word.js

@@ -0,0 +1,112 @@
+class Word {
+  constructor({ id, word, clue, topic, difficulty = 'medium', length }) {
+    this.id = id;
+    this.word = word.toUpperCase();
+    this.clue = clue;
+    this.topic = topic;
+    this.difficulty = difficulty;
+    this.length = length || word.length;
+    this.createdAt = new Date();
+  }
+
+  static validateWord(wordData) {
+    const errors = [];
+    
+    if (!wordData.word || typeof wordData.word !== 'string') {
+      errors.push('Word is required and must be a string');
+    } else if (wordData.word.length < 2 || wordData.word.length > 15) {
+      errors.push('Word must be between 2 and 15 characters');
+    } else if (!/^[A-Za-z]+$/.test(wordData.word)) {
+      errors.push('Word must contain only letters');
+    }
+    
+    if (!wordData.clue || typeof wordData.clue !== 'string') {
+      errors.push('Clue is required and must be a string');
+    }
+    
+    if (!wordData.topic || typeof wordData.topic !== 'string') {
+      errors.push('Topic is required and must be a string');
+    }
+    
+    if (wordData.difficulty && !['easy', 'medium', 'hard'].includes(wordData.difficulty)) {
+      errors.push('Difficulty must be easy, medium, or hard');
+    }
+    
+    return {
+      isValid: errors.length === 0,
+      errors
+    };
+  }
+
+  static fromJSON(data) {
+    return new Word(data);
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      word: this.word,
+      clue: this.clue,
+      topic: this.topic,
+      difficulty: this.difficulty,
+      length: this.length,
+      createdAt: this.createdAt
+    };
+  }
+
+  getDifficultyScore() {
+    const baseScore = this.length;
+    const difficultyMultiplier = {
+      easy: 1,
+      medium: 1.2,
+      hard: 1.5
+    };
+    
+    return Math.round(baseScore * (difficultyMultiplier[this.difficulty] || 1));
+  }
+
+  isCompatibleWith(otherWord) {
+    if (!otherWord || !(otherWord instanceof Word)) {
+      return false;
+    }
+    
+    const thisWord = this.word;
+    const otherWordStr = otherWord.word;
+    
+    for (let i = 0; i < thisWord.length; i++) {
+      for (let j = 0; j < otherWordStr.length; j++) {
+        if (thisWord[i] === otherWordStr[j]) {
+          return true;
+        }
+      }
+    }
+    
+    return false;
+  }
+
+  getIntersectionPoints(otherWord) {
+    if (!this.isCompatibleWith(otherWord)) {
+      return [];
+    }
+    
+    const intersections = [];
+    const thisWord = this.word;
+    const otherWordStr = otherWord.word;
+    
+    for (let i = 0; i < thisWord.length; i++) {
+      for (let j = 0; j < otherWordStr.length; j++) {
+        if (thisWord[i] === otherWordStr[j]) {
+          intersections.push({
+            thisIndex: i,
+            otherIndex: j,
+            letter: thisWord[i]
+          });
+        }
+      }
+    }
+    
+    return intersections;
+  }
+}
+
+module.exports = Word;

crossword-app/backend/src/routes/api.js

@@ -0,0 +1,22 @@
+const express = require('express');
+const PuzzleController = require('../controllers/puzzleController');
+
+const router = express.Router();
+
+router.get('/topics', PuzzleController.getTopics);
+
+router.post('/generate', PuzzleController.generatePuzzle);
+
+router.post('/validate', PuzzleController.validateAnswers);
+
+router.get('/words/:topic', PuzzleController.getWords);
+
+router.get('/health', (req, res) => {
+  res.json({ 
+    status: 'OK', 
+    timestamp: new Date().toISOString(),
+    service: 'Crossword API'
+  });
+});
+
+module.exports = router;

crossword-app/backend/src/services/crosswordGenerator.js

@@ -0,0 +1,313 @@
+const WordService = require('./wordService');
+
+class CrosswordGenerator {
+  constructor() {
+    this.maxAttempts = 100;
+    this.minWords = 6;
+    this.maxWords = 12;
+  }
+
+  async generatePuzzle(topics, difficulty = 'medium') {
+    try {
+      const words = await this.selectWords(topics, difficulty);
+      if (words.length < this.minWords) {
+        throw new Error('Not enough words available for selected topics');
+      }
+
+      const gridResult = this.createGrid(words);
+      if (!gridResult) {
+        throw new Error('Could not place words in grid');
+      }
+
+      const clues = this.generateClues(words, gridResult.placedWords);
+      
+      return {
+        grid: gridResult.grid,
+        clues: clues,
+        metadata: {
+          topics,
+          difficulty,
+          wordCount: words.length,
+          size: gridResult.size
+        }
+      };
+    } catch (error) {
+      console.error('Error generating puzzle:', error);
+      return null;
+    }
+  }
+
+  async selectWords(topics, difficulty) {
+    const allWords = [];
+    
+    for (const topic of topics) {
+      const topicWords = await WordService.getWordsByTopic(topic);
+      allWords.push(...topicWords);
+    }
+
+    const filteredWords = this.filterWordsByDifficulty(allWords, difficulty);
+    const shuffled = this.shuffleArray(filteredWords);
+    
+    return shuffled.slice(0, this.maxWords);
+  }
+
+  filterWordsByDifficulty(words, difficulty) {
+    const difficultyMap = {
+      easy: { minLen: 3, maxLen: 7 },
+      medium: { minLen: 4, maxLen: 10 },
+      hard: { minLen: 5, maxLen: 15 }
+    };
+    
+    const { minLen, maxLen } = difficultyMap[difficulty] || difficultyMap.medium;
+    
+    return words.filter(word => 
+      word.word.length >= minLen && word.word.length <= maxLen
+    );
+  }
+
+  createGrid(words) {
+    if (!words || words.length === 0) return null;
+
+    const wordList = words.map(w => w.word.toUpperCase()).sort((a, b) => b.length - a.length);
+    const size = this.calculateGridSize(wordList);
+    
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const currentSize = size + attempt;
+      const result = this.placeWordsInGrid(wordList, currentSize);
+      if (result) {
+        return { grid: result.grid, size: currentSize, placedWords: result.placedWords };
+      }
+    }
+    
+    return null;
+  }
+
+  calculateGridSize(words) {
+    const totalChars = words.reduce((sum, word) => sum + word.length, 0);
+    const longestWord = Math.max(...words.map(word => word.length));
+    return Math.max(
+      Math.ceil(Math.sqrt(totalChars * 1.5)),
+      longestWord,
+      8
+    );
+  }
+
+  trimGrid(grid, placedWords) {
+    if (!placedWords || placedWords.length === 0) return grid;
+    
+    // Find the bounds of the actual puzzle
+    let minRow = grid.length, maxRow = -1;
+    let minCol = grid[0].length, maxCol = -1;
+    
+    placedWords.forEach(word => {
+      const { row, col, direction } = word;
+      const wordLength = word.word.length;
+      
+      minRow = Math.min(minRow, row);
+      minCol = Math.min(minCol, col);
+      
+      if (direction === 'horizontal') {
+        maxRow = Math.max(maxRow, row);
+        maxCol = Math.max(maxCol, col + wordLength - 1);
+      } else {
+        maxRow = Math.max(maxRow, row + wordLength - 1);
+        maxCol = Math.max(maxCol, col);
+      }
+    });
+    
+    // Add small padding
+    minRow = Math.max(0, minRow - 1);
+    minCol = Math.max(0, minCol - 1);
+    maxRow = Math.min(grid.length - 1, maxRow + 1);
+    maxCol = Math.min(grid[0].length - 1, maxCol + 1);
+    
+    // Create trimmed grid
+    const trimmedGrid = [];
+    for (let r = minRow; r <= maxRow; r++) {
+      const row = [];
+      for (let c = minCol; c <= maxCol; c++) {
+        row.push(grid[r][c]);
+      }
+      trimmedGrid.push(row);
+    }
+    
+    // Update placed words positions to match trimmed grid
+    const updatedPlacedWords = placedWords.map(word => ({
+      ...word,
+      row: word.row - minRow,
+      col: word.col - minCol
+    }));
+    
+    return { grid: trimmedGrid, placedWords: updatedPlacedWords };
+  }
+
+  placeWordsInGrid(words, size) {
+    const grid = Array(size).fill().map(() => Array(size).fill('.'));
+    const placedWords = [];
+    
+    if (this.backtrackPlacement(grid, words, 0, placedWords)) {
+      const trimmed = this.trimGrid(grid, placedWords);
+      return { grid: trimmed.grid, placedWords: trimmed.placedWords };
+    }
+    
+    return null;
+  }
+
+  backtrackPlacement(grid, words, wordIndex, placedWords) {
+    if (wordIndex >= words.length) {
+      return true;
+    }
+
+    const word = words[wordIndex];
+    const size = grid.length;
+
+    for (let row = 0; row < size; row++) {
+      for (let col = 0; col < size; col++) {
+        for (const direction of ['horizontal', 'vertical']) {
+          if (this.canPlaceWord(grid, word, row, col, direction)) {
+            const originalState = this.placeWord(grid, word, row, col, direction);
+            placedWords.push({ word, row, col, direction, number: wordIndex + 1 });
+            
+            if (this.backtrackPlacement(grid, words, wordIndex + 1, placedWords)) {
+              return true;
+            }
+            
+            this.removeWord(grid, originalState);
+            placedWords.pop();
+          }
+        }
+      }
+    }
+    
+    return false;
+  }
+
+  canPlaceWord(grid, word, row, col, direction) {
+    const size = grid.length;
+    
+    if (direction === 'horizontal') {
+      if (col + word.length > size) return false;
+      
+      for (let i = 0; i < word.length; i++) {
+        const currentCell = grid[row][col + i];
+        if (currentCell !== '.' && currentCell !== word[i]) {
+          return false;
+        }
+      }
+    } else {
+      if (row + word.length > size) return false;
+      
+      for (let i = 0; i < word.length; i++) {
+        const currentCell = grid[row + i][col];
+        if (currentCell !== '.' && currentCell !== word[i]) {
+          return false;
+        }
+      }
+    }
+    
+    return this.validateWordPlacement(grid, word, row, col, direction);
+  }
+
+  validateWordPlacement(grid, word, row, col, direction) {
+    const size = grid.length;
+    
+    if (direction === 'horizontal') {
+      if (col > 0 && grid[row][col - 1] !== '.') return false;
+      if (col + word.length < size && grid[row][col + word.length] !== '.') return false;
+    } else {
+      if (row > 0 && grid[row - 1][col] !== '.') return false;
+      if (row + word.length < size && grid[row + word.length][col] !== '.') return false;
+    }
+    
+    return true;
+  }
+
+  placeWord(grid, word, row, col, direction) {
+    const originalState = [];
+    
+    if (direction === 'horizontal') {
+      for (let i = 0; i < word.length; i++) {
+        originalState.push({
+          row: row,
+          col: col + i,
+          value: grid[row][col + i]
+        });
+        grid[row][col + i] = word[i];
+      }
+    } else {
+      for (let i = 0; i < word.length; i++) {
+        originalState.push({
+          row: row + i,
+          col: col,
+          value: grid[row + i][col]
+        });
+        grid[row + i][col] = word[i];
+      }
+    }
+    
+    return originalState;
+  }
+
+  removeWord(grid, originalState) {
+    originalState.forEach(state => {
+      grid[state.row][state.col] = state.value;
+    });
+  }
+
+  generateClues(words, placedWords) {
+    return placedWords.map((placedWord, index) => {
+      // Find the word object that matches this placed word
+      const wordObj = words.find(w => w.word.toUpperCase() === placedWord.word);
+      
+      return {
+        number: index + 1,
+        word: placedWord.word,
+        text: wordObj ? (wordObj.clue || `Clue for ${placedWord.word}`) : `Clue for ${placedWord.word}`,
+        direction: placedWord.direction === 'horizontal' ? 'across' : 'down',
+        position: { row: placedWord.row, col: placedWord.col }
+      };
+    });
+  }
+
+  static validateAnswers(puzzle, userAnswers) {
+    const correct = {};
+    const incorrect = {};
+    let totalCorrect = 0;
+    let totalCells = 0;
+
+    puzzle.grid.forEach((row, rowIndex) => {
+      row.forEach((cell, colIndex) => {
+        if (cell !== '.') {
+          totalCells++;
+          const key = `${rowIndex}-${colIndex}`;
+          const userAnswer = userAnswers[key];
+          
+          if (userAnswer === cell) {
+            correct[key] = true;
+            totalCorrect++;
+          } else if (userAnswer) {
+            incorrect[key] = true;
+          }
+        }
+      });
+    });
+
+    return {
+      correct,
+      incorrect,
+      isComplete: totalCorrect === totalCells,
+      progress: totalCells > 0 ? (totalCorrect / totalCells) * 100 : 0
+    };
+  }
+
+  shuffleArray(array) {
+    const shuffled = [...array];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+  }
+}
+
+module.exports = CrosswordGenerator;

crossword-app/backend/src/services/wordService.js

@@ -0,0 +1,123 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+class WordService {
+  constructor() {
+    this.wordsCache = new Map();
+    this.topicsCache = null;
+  }
+
+  async getAllTopics() {
+    if (this.topicsCache) {
+      return this.topicsCache;
+    }
+
+    try {
+      const dataDir = path.join(__dirname, '../../data/word-lists');
+      const files = await fs.readdir(dataDir);
+      
+      const topics = files
+        .filter(file => file.endsWith('.json'))
+        .map(file => ({
+          id: file.replace('.json', ''),
+          name: this.formatTopicName(file.replace('.json', ''))
+        }));
+
+      this.topicsCache = topics;
+      return topics;
+    } catch (error) {
+      console.error('Error loading topics:', error);
+      return this.getDefaultTopics();
+    }
+  }
+
+  async getWordsByTopic(topicName) {
+    const cacheKey = topicName.toLowerCase();
+    
+    if (this.wordsCache.has(cacheKey)) {
+      return this.wordsCache.get(cacheKey);
+    }
+
+    try {
+      const filePath = path.join(__dirname, '../../data/word-lists', `${topicName.toLowerCase()}.json`);
+      const fileContent = await fs.readFile(filePath, 'utf8');
+      const words = JSON.parse(fileContent);
+      
+      this.wordsCache.set(cacheKey, words);
+      return words;
+    } catch (error) {
+      console.error(`Error loading words for topic ${topicName}:`, error);
+      return this.getDefaultWords(topicName);
+    }
+  }
+
+  formatTopicName(fileName) {
+    return fileName
+      .split('-')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  getDefaultTopics() {
+    return [
+      { id: 'animals', name: 'Animals' },
+      { id: 'science', name: 'Science' },
+      { id: 'geography', name: 'Geography' },
+      { id: 'technology', name: 'Technology' }
+    ];
+  }
+
+  getDefaultWords(topic) {
+    const defaultWordSets = {
+      animals: [
+        { word: 'DOG', clue: 'Man\'s best friend' },
+        { word: 'CAT', clue: 'Feline pet' },
+        { word: 'ELEPHANT', clue: 'Large mammal with trunk' },
+        { word: 'TIGER', clue: 'Striped big cat' },
+        { word: 'WHALE', clue: 'Largest marine mammal' },
+        { word: 'BUTTERFLY', clue: 'Colorful flying insect' },
+        { word: 'BIRD', clue: 'Flying creature with feathers' },
+        { word: 'FISH', clue: 'Aquatic animal with gills' }
+      ],
+      science: [
+        { word: 'ATOM', clue: 'Smallest unit of matter' },
+        { word: 'GRAVITY', clue: 'Force that pulls objects down' },
+        { word: 'MOLECULE', clue: 'Group of atoms bonded together' },
+        { word: 'PHOTON', clue: 'Particle of light' },
+        { word: 'CHEMISTRY', clue: 'Study of matter and reactions' },
+        { word: 'PHYSICS', clue: 'Study of matter and energy' },
+        { word: 'BIOLOGY', clue: 'Study of living organisms' },
+        { word: 'ELEMENT', clue: 'Pure chemical substance' }
+      ],
+      geography: [
+        { word: 'MOUNTAIN', clue: 'High elevation landform' },
+        { word: 'OCEAN', clue: 'Large body of salt water' },
+        { word: 'DESERT', clue: 'Dry, arid region' },
+        { word: 'CONTINENT', clue: 'Large landmass' },
+        { word: 'RIVER', clue: 'Flowing body of water' },
+        { word: 'ISLAND', clue: 'Land surrounded by water' },
+        { word: 'FOREST', clue: 'Dense area of trees' },
+        { word: 'VALLEY', clue: 'Low area between hills' }
+      ],
+      technology: [
+        { word: 'COMPUTER', clue: 'Electronic processing device' },
+        { word: 'INTERNET', clue: 'Global computer network' },
+        { word: 'ALGORITHM', clue: 'Set of rules for solving problems' },
+        { word: 'DATABASE', clue: 'Organized collection of data' },
+        { word: 'SOFTWARE', clue: 'Computer programs' },
+        { word: 'ROBOT', clue: 'Automated machine' },
+        { word: 'NETWORK', clue: 'Connected system of computers' },
+        { word: 'CODE', clue: 'Programming instructions' }
+      ]
+    };
+
+    return defaultWordSets[topic.toLowerCase()] || [];
+  }
+
+  clearCache() {
+    this.wordsCache.clear();
+    this.topicsCache = null;
+  }
+}
+
+module.exports = new WordService();

crossword-app/database/migrations/001_initial_schema.sql

@@ -0,0 +1,91 @@
+-- Initial database schema for crossword puzzle application
+-- This migration creates the basic tables for topics, words, and clues
+
+CREATE TABLE IF NOT EXISTS topics (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(100) NOT NULL UNIQUE,
+    description TEXT,
+    difficulty VARCHAR(20) DEFAULT 'medium' CHECK (difficulty IN ('easy', 'medium', 'hard')),
+    word_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS words (
+    id SERIAL PRIMARY KEY,
+    word VARCHAR(50) NOT NULL,
+    length INTEGER NOT NULL,
+    topic_id INTEGER REFERENCES topics(id) ON DELETE CASCADE,
+    difficulty VARCHAR(20) DEFAULT 'medium' CHECK (difficulty IN ('easy', 'medium', 'hard')),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT unique_word_topic UNIQUE (word, topic_id)
+);
+
+CREATE TABLE IF NOT EXISTS clues (
+    id SERIAL PRIMARY KEY,
+    word_id INTEGER REFERENCES words(id) ON DELETE CASCADE,
+    clue_text TEXT NOT NULL,
+    difficulty VARCHAR(20) DEFAULT 'medium' CHECK (difficulty IN ('easy', 'medium', 'hard')),
+    is_primary BOOLEAN DEFAULT true,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS generated_puzzles (
+    id SERIAL PRIMARY KEY,
+    grid_data JSONB NOT NULL,
+    clues_data JSONB NOT NULL,
+    metadata JSONB,
+    topics TEXT[] NOT NULL,
+    difficulty VARCHAR(20) DEFAULT 'medium',
+    word_count INTEGER,
+    grid_size INTEGER,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    expires_at TIMESTAMP WITH TIME ZONE DEFAULT (CURRENT_TIMESTAMP + INTERVAL '24 hours')
+);
+
+-- Indexes for better query performance
+CREATE INDEX IF NOT EXISTS idx_words_topic_id ON words(topic_id);
+CREATE INDEX IF NOT EXISTS idx_words_length ON words(length);
+CREATE INDEX IF NOT EXISTS idx_words_difficulty ON words(difficulty);
+CREATE INDEX IF NOT EXISTS idx_clues_word_id ON clues(word_id);
+CREATE INDEX IF NOT EXISTS idx_clues_primary ON clues(is_primary);
+CREATE INDEX IF NOT EXISTS idx_puzzles_topics ON generated_puzzles USING GIN(topics);
+CREATE INDEX IF NOT EXISTS idx_puzzles_difficulty ON generated_puzzles(difficulty);
+CREATE INDEX IF NOT EXISTS idx_puzzles_expires ON generated_puzzles(expires_at);
+
+-- Function to update word count in topics table
+CREATE OR REPLACE FUNCTION update_topic_word_count()
+RETURNS TRIGGER AS $$
+BEGIN
+    IF TG_OP = 'INSERT' THEN
+        UPDATE topics 
+        SET word_count = word_count + 1, updated_at = CURRENT_TIMESTAMP
+        WHERE id = NEW.topic_id;
+        RETURN NEW;
+    ELSIF TG_OP = 'DELETE' THEN
+        UPDATE topics 
+        SET word_count = word_count - 1, updated_at = CURRENT_TIMESTAMP
+        WHERE id = OLD.topic_id;
+        RETURN OLD;
+    END IF;
+    RETURN NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Trigger to automatically update word count
+CREATE TRIGGER trigger_update_word_count
+    AFTER INSERT OR DELETE ON words
+    FOR EACH ROW
+    EXECUTE FUNCTION update_topic_word_count();
+
+-- Function to clean up expired puzzles
+CREATE OR REPLACE FUNCTION cleanup_expired_puzzles()
+RETURNS INTEGER AS $$
+DECLARE
+    deleted_count INTEGER;
+BEGIN
+    DELETE FROM generated_puzzles WHERE expires_at < CURRENT_TIMESTAMP;
+    GET DIAGNOSTICS deleted_count = ROW_COUNT;
+    RETURN deleted_count;
+END;
+$$ LANGUAGE plpgsql;

crossword-app/database/seeds/seed_data.sql

@@ -0,0 +1,214 @@
+-- Seed data for crossword puzzle application
+-- This file populates the database with initial topics and words
+
+-- Insert topics
+INSERT INTO topics (name, description, difficulty) VALUES
+('Animals', 'Various animals from around the world', 'easy'),
+('Science', 'Scientific terms and concepts', 'medium'),
+('Geography', 'Countries, cities, and geographical features', 'medium'),
+('Technology', 'Computer and technology terms', 'hard'),
+('History', 'Historical events and figures', 'hard'),
+('Sports', 'Sports and athletic activities', 'easy')
+ON CONFLICT (name) DO NOTHING;
+
+-- Insert words and clues for Animals topic
+WITH animal_topic AS (SELECT id FROM topics WHERE name = 'Animals')
+INSERT INTO words (word, length, topic_id, difficulty) 
+SELECT word_data.word, LENGTH(word_data.word), animal_topic.id, 'easy'
+FROM animal_topic,
+(VALUES 
+    ('DOG'), ('CAT'), ('ELEPHANT'), ('TIGER'), ('WHALE'), 
+    ('BUTTERFLY'), ('BIRD'), ('FISH'), ('LION'), ('BEAR'),
+    ('RABBIT'), ('HORSE'), ('SHEEP'), ('GOAT'), ('DUCK'),
+    ('CHICKEN'), ('SNAKE'), ('TURTLE'), ('FROG'), ('SHARK'),
+    ('DOLPHIN'), ('PENGUIN'), ('MONKEY'), ('ZEBRA'), ('GIRAFFE')
+) AS word_data(word)
+ON CONFLICT (word, topic_id) DO NOTHING;
+
+-- Insert clues for animals
+WITH animal_words AS (
+    SELECT w.id, w.word 
+    FROM words w 
+    JOIN topics t ON w.topic_id = t.id 
+    WHERE t.name = 'Animals'
+)
+INSERT INTO clues (word_id, clue_text, difficulty)
+SELECT aw.id, clue_data.clue, 'easy'
+FROM animal_words aw
+JOIN (VALUES 
+    ('DOG', 'Man''s best friend'),
+    ('CAT', 'Feline pet that purrs'),
+    ('ELEPHANT', 'Large mammal with a trunk'),
+    ('TIGER', 'Striped big cat'),
+    ('WHALE', 'Largest marine mammal'),
+    ('BUTTERFLY', 'Colorful flying insect'),
+    ('BIRD', 'Flying creature with feathers'),
+    ('FISH', 'Aquatic animal with gills'),
+    ('LION', 'King of the jungle'),
+    ('BEAR', 'Large mammal that hibernates'),
+    ('RABBIT', 'Hopping mammal with long ears'),
+    ('HORSE', 'Riding animal with hooves'),
+    ('SHEEP', 'Woolly farm animal'),
+    ('GOAT', 'Horned farm animal'),
+    ('DUCK', 'Water bird that quacks'),
+    ('CHICKEN', 'Farm bird that lays eggs'),
+    ('SNAKE', 'Slithering reptile'),
+    ('TURTLE', 'Shelled reptile'),
+    ('FROG', 'Amphibian that croaks'),
+    ('SHARK', 'Predatory ocean fish'),
+    ('DOLPHIN', 'Intelligent marine mammal'),
+    ('PENGUIN', 'Flightless Antarctic bird'),
+    ('MONKEY', 'Primate that swings in trees'),
+    ('ZEBRA', 'Striped African animal'),
+    ('GIRAFFE', 'Tallest land animal')
+) AS clue_data(word, clue) ON aw.word = clue_data.word;
+
+-- Insert words and clues for Science topic
+WITH science_topic AS (SELECT id FROM topics WHERE name = 'Science')
+INSERT INTO words (word, length, topic_id, difficulty) 
+SELECT word_data.word, LENGTH(word_data.word), science_topic.id, 'medium'
+FROM science_topic,
+(VALUES 
+    ('ATOM'), ('GRAVITY'), ('MOLECULE'), ('PHOTON'), ('CHEMISTRY'),
+    ('PHYSICS'), ('BIOLOGY'), ('ELEMENT'), ('OXYGEN'), ('CARBON'),
+    ('HYDROGEN'), ('ENERGY'), ('FORCE'), ('VELOCITY'), ('MASS'),
+    ('VOLUME'), ('DENSITY'), ('PRESSURE'), ('ELECTRON'), ('PROTON'),
+    ('NEUTRON'), ('NUCLEUS'), ('CELL'), ('DNA'), ('PROTEIN')
+) AS word_data(word)
+ON CONFLICT (word, topic_id) DO NOTHING;
+
+-- Insert clues for science
+WITH science_words AS (
+    SELECT w.id, w.word 
+    FROM words w 
+    JOIN topics t ON w.topic_id = t.id 
+    WHERE t.name = 'Science'
+)
+INSERT INTO clues (word_id, clue_text, difficulty)
+SELECT sw.id, clue_data.clue, 'medium'
+FROM science_words sw
+JOIN (VALUES 
+    ('ATOM', 'Smallest unit of matter'),
+    ('GRAVITY', 'Force that pulls objects down'),
+    ('MOLECULE', 'Group of atoms bonded together'),
+    ('PHOTON', 'Particle of light'),
+    ('CHEMISTRY', 'Study of matter and reactions'),
+    ('PHYSICS', 'Study of matter and energy'),
+    ('BIOLOGY', 'Study of living organisms'),
+    ('ELEMENT', 'Pure chemical substance'),
+    ('OXYGEN', 'Gas essential for breathing'),
+    ('CARBON', 'Element found in all life'),
+    ('HYDROGEN', 'Lightest chemical element'),
+    ('ENERGY', 'Capacity to do work'),
+    ('FORCE', 'Push or pull on an object'),
+    ('VELOCITY', 'Speed with direction'),
+    ('MASS', 'Amount of matter in object'),
+    ('VOLUME', 'Amount of space occupied'),
+    ('DENSITY', 'Mass per unit volume'),
+    ('PRESSURE', 'Force per unit area'),
+    ('ELECTRON', 'Negatively charged particle'),
+    ('PROTON', 'Positively charged particle'),
+    ('NEUTRON', 'Neutral atomic particle'),
+    ('NUCLEUS', 'Center of an atom'),
+    ('CELL', 'Basic unit of life'),
+    ('DNA', 'Genetic blueprint molecule'),
+    ('PROTEIN', 'Complex biological molecule')
+) AS clue_data(word, clue) ON sw.word = clue_data.word;
+
+-- Insert words and clues for Geography topic
+WITH geography_topic AS (SELECT id FROM topics WHERE name = 'Geography')
+INSERT INTO words (word, length, topic_id, difficulty) 
+SELECT word_data.word, LENGTH(word_data.word), geography_topic.id, 'medium'
+FROM geography_topic,
+(VALUES 
+    ('MOUNTAIN'), ('OCEAN'), ('DESERT'), ('CONTINENT'), ('RIVER'),
+    ('ISLAND'), ('FOREST'), ('VALLEY'), ('LAKE'), ('BEACH'),
+    ('PLATEAU'), ('CANYON'), ('GLACIER'), ('VOLCANO'), ('EQUATOR'),
+    ('LATITUDE'), ('CLIMATE'), ('CAPITAL'), ('BORDER'), ('COAST')
+) AS word_data(word)
+ON CONFLICT (word, topic_id) DO NOTHING;
+
+-- Insert clues for geography
+WITH geography_words AS (
+    SELECT w.id, w.word 
+    FROM words w 
+    JOIN topics t ON w.topic_id = t.id 
+    WHERE t.name = 'Geography'
+)
+INSERT INTO clues (word_id, clue_text, difficulty)
+SELECT gw.id, clue_data.clue, 'medium'
+FROM geography_words gw
+JOIN (VALUES 
+    ('MOUNTAIN', 'High elevation landform'),
+    ('OCEAN', 'Large body of salt water'),
+    ('DESERT', 'Dry, arid region'),
+    ('CONTINENT', 'Large landmass'),
+    ('RIVER', 'Flowing body of water'),
+    ('ISLAND', 'Land surrounded by water'),
+    ('FOREST', 'Dense area of trees'),
+    ('VALLEY', 'Low area between hills'),
+    ('LAKE', 'Body of freshwater'),
+    ('BEACH', 'Sandy shore by water'),
+    ('PLATEAU', 'Elevated flat area'),
+    ('CANYON', 'Deep gorge with steep sides'),
+    ('GLACIER', 'Moving mass of ice'),
+    ('VOLCANO', 'Mountain that erupts'),
+    ('EQUATOR', 'Earth''s middle line'),
+    ('LATITUDE', 'Distance from equator'),
+    ('CLIMATE', 'Long-term weather pattern'),
+    ('CAPITAL', 'Main city of country'),
+    ('BORDER', 'Boundary between countries'),
+    ('COAST', 'Land meeting the sea')
+) AS clue_data(word, clue) ON gw.word = clue_data.word;
+
+-- Insert words and clues for Technology topic
+WITH technology_topic AS (SELECT id FROM topics WHERE name = 'Technology')
+INSERT INTO words (word, length, topic_id, difficulty) 
+SELECT word_data.word, LENGTH(word_data.word), technology_topic.id, 'hard'
+FROM technology_topic,
+(VALUES 
+    ('COMPUTER'), ('INTERNET'), ('ALGORITHM'), ('DATABASE'), ('SOFTWARE'),
+    ('HARDWARE'), ('NETWORK'), ('CODE'), ('ROBOT'), ('DIGITAL'),
+    ('PROCESSOR'), ('MEMORY'), ('KEYBOARD'), ('MONITOR'), ('MOUSE'),
+    ('SMARTPHONE'), ('TABLET'), ('LAPTOP'), ('SERVER'), ('CLOUD'),
+    ('WEBSITE'), ('EMAIL'), ('BROWSER'), ('SEARCH'), ('DOWNLOAD')
+) AS word_data(word)
+ON CONFLICT (word, topic_id) DO NOTHING;
+
+-- Insert clues for technology
+WITH technology_words AS (
+    SELECT w.id, w.word 
+    FROM words w 
+    JOIN topics t ON w.topic_id = t.id 
+    WHERE t.name = 'Technology'
+)
+INSERT INTO clues (word_id, clue_text, difficulty)
+SELECT tw.id, clue_data.clue, 'hard'
+FROM technology_words tw
+JOIN (VALUES 
+    ('COMPUTER', 'Electronic processing device'),
+    ('INTERNET', 'Global computer network'),
+    ('ALGORITHM', 'Set of rules for solving problems'),
+    ('DATABASE', 'Organized collection of data'),
+    ('SOFTWARE', 'Computer programs'),
+    ('HARDWARE', 'Physical computer components'),
+    ('NETWORK', 'Connected system of computers'),
+    ('CODE', 'Programming instructions'),
+    ('ROBOT', 'Automated machine'),
+    ('DIGITAL', 'Using binary data'),
+    ('PROCESSOR', 'Computer''s brain'),
+    ('MEMORY', 'Data storage component'),
+    ('KEYBOARD', 'Input device with keys'),
+    ('MONITOR', 'Computer display screen'),
+    ('MOUSE', 'Pointing input device'),
+    ('SMARTPHONE', 'Portable computing device'),
+    ('TABLET', 'Touchscreen computing device'),
+    ('LAPTOP', 'Portable computer'),
+    ('SERVER', 'Computer that serves data'),
+    ('CLOUD', 'Internet-based computing'),
+    ('WEBSITE', 'Collection of web pages'),
+    ('EMAIL', 'Electronic mail'),
+    ('BROWSER', 'Web navigation software'),
+    ('SEARCH', 'Look for information'),
+    ('DOWNLOAD', 'Transfer data to device')
+) AS clue_data(word, clue) ON tw.word = clue_data.word;

crossword-app/frontend/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Generate custom crossword puzzles by selecting topics" />
+    <meta name="keywords" content="crossword, puzzle, word game, brain teaser" />
+    <title>Crossword Puzzle Generator</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

crossword-app/frontend/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "crossword-frontend",
+  "version": "1.0.0",
+  "description": "React frontend for crossword puzzle generator",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint . --ext js,jsx --fix",
+    "format": "prettier --write \"src/**/*.{js,jsx,css,md}\""
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "prettier": "^3.1.1",
+    "vite": "^5.0.8"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

crossword-app/frontend/src/App.jsx

@@ -0,0 +1,127 @@
+import React, { useState, useEffect } from 'react';
+import TopicSelector from './components/TopicSelector';
+import PuzzleGrid from './components/PuzzleGrid';
+import ClueList from './components/ClueList';
+import LoadingSpinner from './components/LoadingSpinner';
+import useCrossword from './hooks/useCrossword';
+import './styles/puzzle.css';
+
+function App() {
+  const [selectedTopics, setSelectedTopics] = useState([]);
+  const [difficulty, setDifficulty] = useState('medium');
+  const [showSolution, setShowSolution] = useState(false);
+  
+  const {
+    puzzle,
+    loading,
+    error,
+    topics,
+    fetchTopics,
+    generatePuzzle,
+    resetPuzzle
+  } = useCrossword();
+
+  useEffect(() => {
+    fetchTopics();
+  }, [fetchTopics]);
+
+  const handleGeneratePuzzle = async () => {
+    if (selectedTopics.length === 0) {
+      alert('Please select at least one topic');
+      return;
+    }
+    
+    await generatePuzzle(selectedTopics, difficulty);
+  };
+
+  const handleTopicsChange = (topics) => {
+    setSelectedTopics(topics);
+  };
+
+  const handleReset = () => {
+    resetPuzzle();
+    setSelectedTopics([]);
+    setShowSolution(false);
+  };
+
+  const handleRevealSolution = () => {
+    setShowSolution(true);
+  };
+
+  return (
+    <div className="crossword-app">
+      <header className="app-header">
+        <h1 className="app-title">Crossword Puzzle Generator</h1>
+        <p>Select topics and generate your custom crossword puzzle!</p>
+      </header>
+
+      <TopicSelector 
+        onTopicsChange={handleTopicsChange}
+        availableTopics={topics}
+      />
+
+      <div className="puzzle-controls">
+        <select 
+          value={difficulty} 
+          onChange={(e) => setDifficulty(e.target.value)}
+          className="control-btn"
+        >
+          <option value="easy">Easy</option>
+          <option value="medium">Medium</option>
+          <option value="hard">Hard</option>
+        </select>
+        
+        <button
+          onClick={handleGeneratePuzzle}
+          disabled={loading || selectedTopics.length === 0}
+          className="control-btn generate-btn"
+        >
+          {loading ? 'Generating...' : 'Generate Puzzle'}
+        </button>
+        
+        <button
+          onClick={handleReset}
+          className="control-btn reset-btn"
+        >
+          Reset
+        </button>
+        
+        {puzzle && !showSolution && (
+          <button
+            onClick={handleRevealSolution}
+            className="control-btn reveal-btn"
+          >
+            Reveal Solution
+          </button>
+        )}
+      </div>
+
+      {error && (
+        <div className="error-message">
+          Error: {error}
+        </div>
+      )}
+
+      {loading && <LoadingSpinner />}
+
+      {puzzle && !loading && (
+        <div className="puzzle-layout">
+          <PuzzleGrid 
+            grid={puzzle.grid} 
+            clues={puzzle.clues}
+            showSolution={showSolution}
+          />
+          <ClueList clues={puzzle.clues} />
+        </div>
+      )}
+
+      {!puzzle && !loading && !error && (
+        <div style={{ textAlign: 'center', padding: '40px', color: '#7f8c8d' }}>
+          Select topics and click "Generate Puzzle" to start!
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default App;

crossword-app/frontend/src/components/ClueList.jsx

@@ -0,0 +1,29 @@
+import React from 'react';
+
+const ClueList = ({ clues = [] }) => {
+  const acrossClues = clues.filter(clue => clue.direction === 'across');
+  const downClues = clues.filter(clue => clue.direction === 'down');
+
+  const ClueSection = ({ title, clueList }) => (
+    <div className="clue-section">
+      <h4>{title}</h4>
+      <ol>
+        {clueList.map(clue => (
+          <li key={`${clue.number}-${clue.direction}`} className="clue-item">
+            <span className="clue-number">{clue.number}</span>
+            <span className="clue-text">{clue.text}</span>
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+
+  return (
+    <div className="clue-list">
+      <ClueSection title="Across" clueList={acrossClues} />
+      <ClueSection title="Down" clueList={downClues} />
+    </div>
+  );
+};
+
+export default ClueList;

crossword-app/frontend/src/components/LoadingSpinner.jsx

@@ -0,0 +1,12 @@
+import React from 'react';
+
+const LoadingSpinner = ({ message = "Generating puzzle..." }) => {
+  return (
+    <div className="loading-spinner">
+      <div className="spinner"></div>
+      <p className="loading-message">{message}</p>
+    </div>
+  );
+};
+
+export default LoadingSpinner;

crossword-app/frontend/src/components/PuzzleGrid.jsx

@@ -0,0 +1,77 @@
+import React, { useState } from 'react';
+
+const PuzzleGrid = ({ grid, clues, showSolution, onCellChange }) => {
+  const [userAnswers, setUserAnswers] = useState({});
+
+  const handleCellInput = (row, col, value) => {
+    const key = `${row}-${col}`;
+    const newAnswers = { ...userAnswers, [key]: value.toUpperCase() };
+    setUserAnswers(newAnswers);
+    onCellChange && onCellChange(row, col, value);
+  };
+
+  const getCellValue = (row, col) => {
+    if (showSolution && !isBlackCell(row, col)) {
+      return grid[row][col];
+    }
+    const key = `${row}-${col}`;
+    return userAnswers[key] || '';
+  };
+
+  const isBlackCell = (row, col) => {
+    return grid[row][col] === '.';
+  };
+
+  const getCellNumber = (row, col) => {
+    if (!clues) return null;
+    const clue = clues.find(c => c.position.row === row && c.position.col === col);
+    return clue ? clue.number : null;
+  };
+
+  if (!grid || grid.length === 0) {
+    return <div className="puzzle-grid">No puzzle loaded</div>;
+  }
+
+  const gridRows = grid.length;
+  const gridCols = grid[0] ? grid[0].length : 0;
+
+  return (
+    <div className="puzzle-container">
+      <div 
+        className="puzzle-grid"
+        style={{
+          gridTemplateColumns: `repeat(${gridCols}, 35px)`,
+          gridTemplateRows: `repeat(${gridRows}, 35px)`
+        }}
+      >
+        {grid.map((row, rowIndex) =>
+          row.map((cell, colIndex) => {
+            const cellNumber = getCellNumber(rowIndex, colIndex);
+            return (
+              <div
+                key={`${rowIndex}-${colIndex}`}
+                className={`grid-cell ${isBlackCell(rowIndex, colIndex) ? 'black-cell' : 'white-cell'}`}
+              >
+                {!isBlackCell(rowIndex, colIndex) && (
+                  <>
+                    {cellNumber && <span className="cell-number">{cellNumber}</span>}
+                    <input
+                      type="text"
+                      maxLength="1"
+                      value={getCellValue(rowIndex, colIndex)}
+                      onChange={(e) => handleCellInput(rowIndex, colIndex, e.target.value)}
+                      className={`cell-input ${showSolution ? 'solution-text' : ''}`}
+                      disabled={showSolution}
+                    />
+                  </>
+                )}
+              </div>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default PuzzleGrid;

crossword-app/frontend/src/components/TopicSelector.jsx

@@ -0,0 +1,36 @@
+import React, { useState } from 'react';
+
+const TopicSelector = ({ onTopicsChange, availableTopics = [] }) => {
+  const [selectedTopics, setSelectedTopics] = useState([]);
+
+  const handleTopicToggle = (topic) => {
+    const newSelectedTopics = selectedTopics.includes(topic)
+      ? selectedTopics.filter(t => t !== topic)
+      : [...selectedTopics, topic];
+    
+    setSelectedTopics(newSelectedTopics);
+    onTopicsChange(newSelectedTopics);
+  };
+
+  return (
+    <div className="topic-selector">
+      <h3>Select Topics</h3>
+      <div className="topic-buttons">
+        {availableTopics.map(topic => (
+          <button
+            key={topic.id}
+            className={`topic-btn ${selectedTopics.includes(topic.name) ? 'selected' : ''}`}
+            onClick={() => handleTopicToggle(topic.name)}
+          >
+            {topic.name}
+          </button>
+        ))}
+      </div>
+      <p className="selected-count">
+        {selectedTopics.length} topic{selectedTopics.length !== 1 ? 's' : ''} selected
+      </p>
+    </div>
+  );
+};
+
+export default TopicSelector;

crossword-app/frontend/src/hooks/useCrossword.js

@@ -0,0 +1,93 @@
+import { useState, useCallback } from 'react';
+
+const useCrossword = () => {
+  const [puzzle, setPuzzle] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [topics, setTopics] = useState([]);
+
+  const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:3000';
+
+  const fetchTopics = useCallback(async () => {
+    try {
+      setLoading(true);
+      const response = await fetch(`${API_BASE_URL}/api/topics`);
+      if (!response.ok) throw new Error('Failed to fetch topics');
+      const data = await response.json();
+      setTopics(data);
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  }, [API_BASE_URL]);
+
+  const generatePuzzle = useCallback(async (selectedTopics, difficulty = 'medium') => {
+    try {
+      setLoading(true);
+      setError(null);
+      
+      const response = await fetch(`${API_BASE_URL}/api/generate`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          topics: selectedTopics,
+          difficulty
+        })
+      });
+
+      if (!response.ok) throw new Error('Failed to generate puzzle');
+      
+      const puzzleData = await response.json();
+      setPuzzle(puzzleData);
+      return puzzleData;
+    } catch (err) {
+      setError(err.message);
+      return null;
+    } finally {
+      setLoading(false);
+    }
+  }, [API_BASE_URL]);
+
+  const validateAnswers = useCallback(async (userAnswers) => {
+    try {
+      const response = await fetch(`${API_BASE_URL}/api/validate`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          puzzle: puzzle,
+          answers: userAnswers
+        })
+      });
+
+      if (!response.ok) throw new Error('Failed to validate answers');
+      
+      return await response.json();
+    } catch (err) {
+      setError(err.message);
+      return null;
+    }
+  }, [API_BASE_URL, puzzle]);
+
+  const resetPuzzle = useCallback(() => {
+    setPuzzle(null);
+    setError(null);
+  }, []);
+
+  return {
+    puzzle,
+    loading,
+    error,
+    topics,
+    fetchTopics,
+    generatePuzzle,
+    validateAnswers,
+    resetPuzzle
+  };
+};
+
+export default useCrossword;

crossword-app/frontend/src/main.jsx

@@ -0,0 +1,9 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

crossword-app/frontend/src/styles/puzzle.css

@@ -0,0 +1,332 @@
+/* Crossword Puzzle Styles */
+
+.crossword-app {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 20px;
+  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+}
+
+.app-header {
+  text-align: center;
+  margin-bottom: 30px;
+}
+
+.app-title {
+  color: #2c3e50;
+  font-size: 2.5rem;
+  margin-bottom: 10px;
+}
+
+/* Topic Selector Styles */
+.topic-selector {
+  background: #f8f9fa;
+  padding: 20px;
+  border-radius: 8px;
+  margin-bottom: 20px;
+}
+
+.topic-selector h3 {
+  margin-top: 0;
+  color: #2c3e50;
+}
+
+.topic-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-bottom: 15px;
+}
+
+.topic-btn {
+  padding: 8px 16px;
+  border: 2px solid #3498db;
+  background: white;
+  color: #3498db;
+  border-radius: 20px;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  font-weight: 500;
+}
+
+.topic-btn:hover {
+  background: #3498db;
+  color: white;
+}
+
+.topic-btn.selected {
+  background: #3498db;
+  color: white;
+}
+
+.selected-count {
+  color: #7f8c8d;
+  font-size: 0.9rem;
+  margin: 0;
+}
+
+/* Puzzle Controls */
+.puzzle-controls {
+  display: flex;
+  gap: 15px;
+  margin-bottom: 20px;
+  justify-content: center;
+}
+
+.control-btn {
+  padding: 10px 20px;
+  border: none;
+  border-radius: 5px;
+  cursor: pointer;
+  font-weight: 600;
+  transition: background-color 0.3s ease;
+}
+
+.generate-btn {
+  background: #27ae60;
+  color: white;
+}
+
+.generate-btn:hover {
+  background: #229954;
+}
+
+.generate-btn:disabled {
+  background: #bdc3c7;
+  cursor: not-allowed;
+}
+
+.reset-btn {
+  background: #e74c3c;
+  color: white;
+}
+
+.reset-btn:hover {
+  background: #c0392b;
+}
+
+.reveal-btn {
+  background: #f39c12;
+  color: white;
+}
+
+.reveal-btn:hover {
+  background: #e67e22;
+}
+
+/* Loading Spinner */
+.loading-spinner {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 40px;
+}
+
+.spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid #f3f3f3;
+  border-top: 4px solid #3498db;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+  margin-bottom: 15px;
+}
+
+@keyframes spin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+
+.loading-message {
+  color: #7f8c8d;
+  font-size: 1.1rem;
+}
+
+/* Puzzle Layout */
+.puzzle-layout {
+  display: grid;
+  grid-template-columns: 1fr 300px;
+  gap: 30px;
+  margin-top: 20px;
+}
+
+@media (max-width: 768px) {
+  .puzzle-layout {
+    grid-template-columns: 1fr;
+    gap: 20px;
+  }
+}
+
+/* Puzzle Grid */
+.puzzle-container {
+  display: flex;
+  justify-content: center;
+}
+
+.puzzle-grid {
+  display: grid;
+  gap: 0;
+  margin: 0 auto;
+  width: fit-content;
+  height: fit-content;
+  border: 2px solid #2c3e50;
+  border-radius: 4px;
+}
+
+.grid-cell {
+  width: 35px;
+  height: 35px;
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  background: white;
+}
+
+.grid-cell::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  border: 1px solid #2c3e50;
+  pointer-events: none;
+  z-index: 10;
+}
+
+.black-cell {
+  background: #2c3e50;
+}
+
+.black-cell::before {
+  background: #2c3e50;
+  border: 1px solid #2c3e50;
+}
+
+.white-cell {
+  background: white;
+}
+
+.cell-input {
+  width: 100%;
+  height: 100%;
+  border: none !important;
+  text-align: center;
+  font-size: 16px;
+  font-weight: bold;
+  background: transparent;
+  outline: none;
+  text-transform: uppercase;
+  position: relative;
+  z-index: 5;
+}
+
+.cell-input:focus {
+  background: #e8f4fd;
+  box-shadow: inset 0 0 0 2px #3498db;
+}
+
+.cell-number {
+  position: absolute;
+  top: 1px;
+  left: 2px;
+  font-size: 10px;
+  font-weight: bold;
+  color: #2c3e50;
+  line-height: 1;
+  z-index: 15;
+  pointer-events: none;
+}
+
+.solution-text {
+  color: #e74c3c !important;
+  font-weight: bold !important;
+  background: #fef9f9 !important;
+}
+
+.solution-text:disabled {
+  opacity: 1 !important;
+  cursor: default;
+}
+
+
+/* Specifically for solution state */
+.grid-cell .solution-text {
+  border: none !important;
+  background: #fef9f9 !important;
+}
+
+/* Clue List */
+.clue-list {
+  background: #f8f9fa;
+  padding: 20px;
+  border-radius: 8px;
+  max-height: 600px;
+  overflow-y: auto;
+}
+
+.clue-section {
+  margin-bottom: 25px;
+}
+
+.clue-section h4 {
+  color: #2c3e50;
+  margin-bottom: 15px;
+  font-size: 1.2rem;
+  border-bottom: 2px solid #3498db;
+  padding-bottom: 5px;
+}
+
+.clue-section ol {
+  padding-left: 0;
+  list-style: none;
+}
+
+.clue-item {
+  display: flex;
+  margin-bottom: 8px;
+  padding: 8px;
+  border-radius: 4px;
+  cursor: pointer;
+  transition: background-color 0.2s ease;
+}
+
+.clue-item:hover {
+  background: #e9ecef;
+}
+
+.clue-number {
+  font-weight: bold;
+  color: #3498db;
+  margin-right: 10px;
+  min-width: 25px;
+}
+
+.clue-text {
+  flex: 1;
+  color: #2c3e50;
+}
+
+/* Error Messages */
+.error-message {
+  background: #f8d7da;
+  color: #721c24;
+  padding: 15px;
+  border-radius: 5px;
+  margin: 20px 0;
+  border: 1px solid #f5c6cb;
+}
+
+/* Success Messages */
+.success-message {
+  background: #d4edda;
+  color: #155724;
+  padding: 15px;
+  border-radius: 5px;
+  margin: 20px 0;
+  border: 1px solid #c3e6cb;
+  text-align: center;
+  font-weight: 600;
+}

crossword-app/frontend/src/utils/gridHelpers.js

@@ -0,0 +1,58 @@
+export const formatGridForDisplay = (grid) => {
+  if (!grid || !Array.isArray(grid)) return [];
+  
+  return grid.map(row => 
+    row.map(cell => cell === '.' ? '.' : cell.toUpperCase())
+  );
+};
+
+export const validateUserInput = (input) => {
+  return /^[A-Za-z]?$/.test(input);
+};
+
+export const checkPuzzleCompletion = (grid, userAnswers) => {
+  if (!grid || !userAnswers) return false;
+  
+  for (let row = 0; row < grid.length; row++) {
+    for (let col = 0; col < grid[row].length; col++) {
+      if (grid[row][col] !== '.') {
+        const key = `${row}-${col}`;
+        if (!userAnswers[key] || userAnswers[key] !== grid[row][col]) {
+          return false;
+        }
+      }
+    }
+  }
+  return true;
+};
+
+export const getWordPositions = (grid, clues) => {
+  const positions = {};
+  
+  clues.forEach(clue => {
+    positions[`${clue.number}-${clue.direction}`] = {
+      start: clue.position,
+      length: clue.word.length,
+      direction: clue.direction
+    };
+  });
+  
+  return positions;
+};
+
+export const highlightWord = (wordPositions, selectedClue) => {
+  if (!selectedClue || !wordPositions[selectedClue]) return [];
+  
+  const { start, length, direction } = wordPositions[selectedClue];
+  const cells = [];
+  
+  for (let i = 0; i < length; i++) {
+    if (direction === 'across') {
+      cells.push(`${start.row}-${start.col + i}`);
+    } else {
+      cells.push(`${start.row + i}-${start.col}`);
+    }
+  }
+  
+  return cells;
+};

crossword-app/frontend/vite.config.js

@@ -0,0 +1,31 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    host: true,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3000',
+        changeOrigin: true,
+        secure: false,
+      }
+    }
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom']
+        }
+      }
+    }
+  },
+  define: {
+    'process.env': process.env
+  }
+})

docs/TODO.md

@@ -0,0 +1,111 @@
+# Crossword Puzzle Webapp - TODO List
+
+## Implementation Tasks
+
+### Phase 1: Project Setup
+- [ ] Set up project structure and initialize repositories
+  - Create frontend/ and backend/ directories
+  - Initialize package.json files
+  - Set up Git repository
+  - Configure ESLint and Prettier
+
+### Phase 2: Database & Data Management
+- [ ] Create database schema and seed data
+  - Design PostgreSQL tables (Topics, Words, Clues)
+  - Create migration scripts
+  - Seed database with initial word lists by topic
+  - Set up Prisma ORM configuration
+
+### Phase 3: Core Algorithm Development
+- [ ] Implement crossword generation algorithm
+  - Word selection logic based on topics
+  - Grid placement algorithm with intersections
+  - Backtracking for conflict resolution
+  - Grid optimization (minimize size, maximize density)
+
+### Phase 4: Backend API
+- [ ] Build backend API endpoints
+  - GET /topics - List available topics
+  - POST /generate - Generate crossword puzzle
+  - POST /validate - Validate user answers
+  - Error handling and validation middleware
+  - CORS configuration
+
+### Phase 5: Frontend Components
+- [ ] Create frontend components (TopicSelector, PuzzleGrid, ClueList)
+  - TopicSelector with multi-select functionality
+  - PuzzleGrid with CSS Grid layout
+  - ClueList component (Across/Down)
+  - LoadingSpinner for generation feedback
+  - PuzzleControls (Reset/New/Difficulty)
+
+### Phase 6: Interactive Features
+- [ ] Implement interactive crossword grid functionality
+  - Click-to-focus input cells
+  - Keyboard navigation (arrow keys, tab)
+  - Real-time input validation
+  - Highlight current word being filled
+  - Auto-advance to next cell
+
+### Phase 7: User Experience
+- [ ] Add puzzle validation and user input handling
+  - Check answers against solution
+  - Provide visual feedback (correct/incorrect)
+  - Show completion status
+  - Reset and new puzzle functionality
+
+### Phase 8: Styling & Polish
+- [ ] Style the application and improve UX
+  - Responsive design for mobile/desktop
+  - Professional color scheme
+  - Smooth animations and transitions
+  - Loading states and error messages
+  - Print-friendly styles
+
+### Phase 9: Environment Setup
+- [ ] Set up development and production environments
+  - Configure environment variables
+  - Set up local development database
+  - Configure build scripts
+  - Set up CI/CD pipeline with GitHub Actions
+
+### Phase 10: Deployment
+- [ ] Deploy application and test end-to-end
+  - Deploy backend to Railway/Heroku
+  - Deploy frontend to Vercel/Netlify
+  - Configure production database
+  - End-to-end testing
+  - Performance optimization
+
+## Detailed Sub-tasks
+
+### Technical Specifications
+- **Database Schema**: See `database-schema.sql`
+- **API Endpoints**: See `api-specification.md`
+
+### Component Props
+```javascript
+// TopicSelector.jsx
+const TopicSelector = ({ topics, selectedTopics, onTopicChange, loading }) => {}
+
+// PuzzleGrid.jsx  
+const PuzzleGrid = ({ grid, onCellChange, currentCell, answers }) => {}
+
+// ClueList.jsx
+const ClueList = ({ clues, direction, onClueClick, completedClues }) => {}
+```
+
+### Key Files to Create
+- `backend/src/services/crosswordGenerator.js` - Core algorithm
+- `backend/src/controllers/puzzleController.js` - API handlers
+- `frontend/src/hooks/useCrossword.js` - State management
+- `frontend/src/utils/gridHelpers.js` - Grid utilities
+- `frontend/src/styles/puzzle.css` - Crossword styling
+
+## Priority Order
+1. Setup project structure and basic backend
+2. Implement word placement algorithm
+3. Create basic frontend with grid display
+4. Add topic selection and API integration
+5. Implement interactive features
+6. Polish UI/UX and deploy

docs/api-specification.md

@@ -0,0 +1,244 @@
+# Crossword Puzzle API Specification
+
+## Base URL
+- Development: `http://localhost:3000/api`
+- Production: `https://your-backend-domain.com/api`
+
+## Authentication
+No authentication required for this MVP version.
+
+## Endpoints
+
+### GET /topics
+Retrieve all available topics for crossword generation.
+
+**Response:**
+```json
+{
+  "topics": [
+    {
+      "id": 1,
+      "name": "Animals",
+      "description": "Creatures from the animal kingdom"
+    },
+    {
+      "id": 2,
+      "name": "Science", 
+      "description": "Scientific terms and concepts"
+    }
+  ]
+}
+```
+
+**Status Codes:**
+- `200 OK` - Success
+- `500 Internal Server Error` - Database error
+
+---
+
+### POST /generate
+Generate a new crossword puzzle based on selected topics and difficulty.
+
+**Request Body:**
+```json
+{
+  "topics": ["Animals", "Science"],
+  "difficulty": "medium",
+  "gridSize": 15
+}
+```
+
+**Parameters:**
+- `topics` (string[]): Array of topic names to include
+- `difficulty` (string): "easy" | "medium" | "hard"
+- `gridSize` (number, optional): Grid size (default: 15)
+
+**Response:**
+```json
+{
+  "puzzle": {
+    "id": "puzzle_123",
+    "grid": [
+      [
+        { "letter": "D", "number": 1, "isBlocked": false },
+        { "letter": "", "number": null, "isBlocked": true }
+      ]
+    ],
+    "clues": {
+      "across": [
+        {
+          "number": 1,
+          "clue": "Man's best friend",
+          "answer": "DOG",
+          "startRow": 0,
+          "startCol": 0,
+          "length": 3
+        }
+      ],
+      "down": [
+        {
+          "number": 2,
+          "clue": "Feline pet",
+          "answer": "CAT", 
+          "startRow": 0,
+          "startCol": 2,
+          "length": 3
+        }
+      ]
+    },
+    "metadata": {
+      "difficulty": "medium",
+      "topics": ["Animals"],
+      "wordCount": 8,
+      "generatedAt": "2024-01-15T10:30:00Z"
+    }
+  }
+}
+```
+
+**Status Codes:**
+- `200 OK` - Puzzle generated successfully
+- `400 Bad Request` - Invalid request parameters
+- `422 Unprocessable Entity` - Unable to generate puzzle with given constraints
+- `500 Internal Server Error` - Generation failed
+
+---
+
+### POST /validate
+Validate user answers against the puzzle solution.
+
+**Request Body:**
+```json
+{
+  "puzzleId": "puzzle_123",
+  "answers": {
+    "1_across": "DOG",
+    "2_down": "CAT"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "validation": {
+    "isComplete": false,
+    "correctCount": 1,
+    "totalCount": 2,
+    "results": {
+      "1_across": {
+        "correct": true,
+        "expected": "DOG",
+        "provided": "DOG"
+      },
+      "2_down": {
+        "correct": false,
+        "expected": "CAT",
+        "provided": "CAR"
+      }
+    }
+  }
+}
+```
+
+**Status Codes:**
+- `200 OK` - Validation completed
+- `400 Bad Request` - Invalid puzzle ID or answers format
+- `404 Not Found` - Puzzle not found
+- `500 Internal Server Error` - Validation failed
+
+---
+
+### GET /words/:topic (Admin/Development)
+Retrieve all words for a specific topic. Useful for development and debugging.
+
+**Parameters:**
+- `topic` (string): Topic name
+
+**Response:**
+```json
+{
+  "topic": "Animals",
+  "words": [
+    {
+      "id": 1,
+      "word": "DOG",
+      "length": 3,
+      "difficulty": 1,
+      "clues": [
+        {
+          "id": 1,
+          "text": "Man's best friend",
+          "difficulty": 1
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Status Codes:**
+- `200 OK` - Words retrieved
+- `404 Not Found` - Topic not found
+- `500 Internal Server Error` - Database error
+
+## Error Response Format
+
+All error responses follow this format:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid difficulty level",
+    "details": {
+      "field": "difficulty",
+      "allowedValues": ["easy", "medium", "hard"]
+    }
+  }
+}
+```
+
+## Rate Limiting
+
+- Generate endpoint: 10 requests per minute per IP
+- Other endpoints: 100 requests per minute per IP
+
+## CORS Configuration
+
+- Allowed origins: Frontend domain(s)
+- Allowed methods: GET, POST, OPTIONS
+- Allowed headers: Content-Type, Authorization
+
+## Data Types
+
+### Grid Cell
+```typescript
+interface GridCell {
+  letter: string;        // Empty string for user input cells
+  number: number | null; // Clue number if cell starts a word
+  isBlocked: boolean;    // True for black squares
+}
+```
+
+### Clue
+```typescript
+interface Clue {
+  number: number;    // Clue number
+  clue: string;      // Clue text
+  answer: string;    // Expected answer
+  startRow: number;  // Starting row in grid
+  startCol: number;  // Starting column in grid
+  length: number;    // Word length
+}
+```
+
+### Puzzle Metadata
+```typescript
+interface PuzzleMetadata {
+  difficulty: 'easy' | 'medium' | 'hard';
+  topics: string[];
+  wordCount: number;
+  generatedAt: string; // ISO timestamp
+}
+```

docs/crossword-app-plan.md

@@ -0,0 +1,217 @@
+# Crossword Puzzle Webapp - Complete Implementation Plan
+
+## Architecture Overview
+
+**Frontend (React/Vue/Vanilla JS)**
+- Topic selection dropdown/buttons
+- Generate puzzle button
+- Interactive crossword grid display
+- Clue lists (across/down)
+
+**Backend (Node.js/Python/Go)**
+- REST API endpoints for puzzle generation
+- Crossword algorithm implementation
+- Word/clue database management
+
+**Database**
+- Word collections organized by topics
+- Clue-answer pairs
+- Pre-generated grids (optional caching)
+
+## Core Components
+
+1. **Topic Management**: Categories like "Animals", "Science", "History"
+2. **Word Selection**: Algorithm to pick words from chosen topic
+3. **Grid Generation**: Place words intersecting on a grid
+4. **Clue Generation**: Match words with appropriate clues
+5. **UI Rendering**: Display interactive puzzle with input fields
+
+## Key Algorithms Needed
+
+- **Grid placement**: Find valid intersections between words
+- **Backtracking**: Handle conflicts when placing words
+- **Difficulty scaling**: Adjust grid size and word complexity
+
+## Tech Stack Suggestions
+
+- **Frontend**: React + CSS Grid for puzzle layout
+- **Backend**: Node.js + Express or Python + Flask
+- **Database**: PostgreSQL or MongoDB for word storage
+- **Deployment**: Vercel/Netlify + Railway/Heroku
+
+## Frontend Components & UI
+
+**Main Page Layout**
+```
+Header: "Crossword Puzzle Generator"
+Topic Selector: Dropdown with categories
+Generate Button: "Create Puzzle"
+Loading State: Spinner during generation
+Puzzle Display: Grid + Clues
+Actions: Reset, New Puzzle, Print
+```
+
+**Components:**
+- `TopicSelector`: Multi-select topics
+- `PuzzleGrid`: Interactive crossword grid
+- `ClueList`: Numbered clues (Across/Down)
+- `LoadingSpinner`: Generation feedback
+- `PuzzleControls`: Reset/New/Difficulty buttons
+
+**UI Flow:**
+1. User selects topic(s)
+2. Clicks generate → Loading state
+3. Puzzle renders with empty grid
+4. User fills in answers
+5. Real-time validation feedback
+
+## Backend API & Crossword Generation
+
+**API Endpoints:**
+```
+GET /topics - List available topics
+POST /generate - Generate puzzle
+  Body: { topics: string[], difficulty: 'easy'|'medium'|'hard' }
+  Response: { grid: Cell[][], clues: Clue[], metadata: {} }
+
+GET /words/:topic - Get words for topic (admin)
+POST /validate - Validate user answers
+```
+
+**Core Algorithm:**
+1. **Word Selection**: Pick 8-15 words from chosen topics
+2. **Grid Placement**: 
+   - Start with longest word horizontally
+   - Find intersections for perpendicular words
+   - Use backtracking for conflicts
+3. **Grid Optimization**: Minimize grid size, maximize word density
+4. **Clue Matching**: Pair each word with appropriate clue
+
+**Generation Logic:**
+```javascript
+class CrosswordGenerator {
+  generatePuzzle(topics, difficulty) {
+    const words = selectWords(topics, difficulty)
+    const grid = createEmptyGrid()
+    const placed = placeWords(words, grid)
+    return { grid, clues: generateClues(placed) }
+  }
+}
+```
+
+## Data Storage & Word Management
+
+**Database Schema:**
+```sql
+Topics: id, name, description
+Words: id, word, length, difficulty_level, topic_id
+Clues: id, word_id, clue_text, difficulty
+Generated_Puzzles: id, grid_data, clues_data, created_at (optional caching)
+```
+
+**Word Collections by Topic:**
+- **Animals**: DOG, ELEPHANT, TIGER, WHALE, BUTTERFLY
+- **Science**: ATOM, GRAVITY, MOLECULE, PHOTON, CHEMISTRY  
+- **Geography**: MOUNTAIN, OCEAN, DESERT, CONTINENT, RIVER
+- **Technology**: COMPUTER, INTERNET, ALGORITHM, DATABASE, SOFTWARE
+
+**Data Sources:**
+- Curated word lists with quality clues
+- Dictionary APIs for definitions
+- Wikipedia API for topic-specific terms
+- Manual curation for puzzle quality
+
+**Storage Strategy:**
+- PostgreSQL for structured word/clue data
+- JSON columns for flexible puzzle metadata
+- Indexing on topic_id and word_length for fast queries
+- Caching layer (Redis) for frequent topic combinations
+
+## Project Structure
+
+```
+crossword-app/
+├── frontend/
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── TopicSelector.jsx
+│   │   │   ├── PuzzleGrid.jsx
+│   │   │   ├── ClueList.jsx
+│   │   │   └── LoadingSpinner.jsx
+│   │   ├── hooks/
+│   │   │   └── useCrossword.js
+│   │   ├── utils/
+│   │   │   └── gridHelpers.js
+│   │   ├── styles/
+│   │   │   └── puzzle.css
+│   │   └── App.jsx
+│   ├── package.json
+│   └── vite.config.js
+├── backend/
+│   ├── src/
+│   │   ├── controllers/
+│   │   │   └── puzzleController.js
+│   │   ├── services/
+│   │   │   ├── crosswordGenerator.js
+│   │   │   └── wordService.js
+│   │   ├── models/
+│   │   │   ├── Word.js
+│   │   │   └── Topic.js
+│   │   ├── routes/
+│   │   │   └── api.js
+│   │   └── app.js
+│   ├── data/
+│   │   └── word-lists/
+│   ├── package.json
+│   └── .env
+└── database/
+    ├── migrations/
+    └── seeds/
+```
+
+**Tech Stack:**
+- **Frontend**: React + Vite, CSS Grid, Axios
+- **Backend**: Node.js + Express, CORS enabled
+- **Database**: PostgreSQL with Prisma ORM
+- **Development**: Nodemon, ESLint, Prettier
+
+## Deployment & Hosting Strategy
+
+**Development Environment:**
+- Local PostgreSQL database
+- Frontend: `npm run dev` (Vite dev server)
+- Backend: `npm run dev` (Nodemon)
+- Environment variables in `.env`
+
+**Production Deployment:**
+- **Frontend**: Vercel or Netlify (static hosting)
+- **Backend**: Railway, Heroku, or DigitalOcean App Platform
+- **Database**: PostgreSQL on Railway/Heroku/AWS RDS
+- **Domain**: Custom domain with HTTPS
+
+**CI/CD Pipeline:**
+- GitHub Actions for automated testing
+- Deploy on push to main branch
+- Environment-specific configs (dev/staging/prod)
+
+**Environment Variables:**
+```
+DATABASE_URL=postgresql://...
+JWT_SECRET=...
+CORS_ORIGIN=https://your-frontend-domain.com
+PORT=3000
+```
+
+**Performance Considerations:**
+- CDN for static assets
+- Database connection pooling
+- API rate limiting
+- Puzzle result caching (Redis)
+
+## Implementation Priority
+
+1. **Phase 1**: Basic word placement algorithm and simple UI
+2. **Phase 2**: Topic selection and word database
+3. **Phase 3**: Interactive grid with validation
+4. **Phase 4**: Polish UI/UX and deployment
+5. **Phase 5**: Advanced features (difficulty levels, saving puzzles)

docs/database-schema.sql

@@ -0,0 +1,72 @@
+-- Crossword Puzzle Webapp Database Schema
+
+-- Topics table
+CREATE TABLE topics (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(50) NOT NULL UNIQUE,
+  description TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Words table  
+CREATE TABLE words (
+  id SERIAL PRIMARY KEY,
+  word VARCHAR(20) NOT NULL,
+  length INTEGER NOT NULL,
+  difficulty_level INTEGER DEFAULT 1 CHECK (difficulty_level BETWEEN 1 AND 3),
+  topic_id INTEGER REFERENCES topics(id) ON DELETE CASCADE,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_topic_length (topic_id, length),
+  INDEX idx_difficulty (difficulty_level)
+);
+
+-- Clues table
+CREATE TABLE clues (
+  id SERIAL PRIMARY KEY,
+  word_id INTEGER REFERENCES words(id) ON DELETE CASCADE,
+  clue_text TEXT NOT NULL,
+  difficulty INTEGER DEFAULT 1 CHECK (difficulty BETWEEN 1 AND 3),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Optional: Generated puzzles cache table
+CREATE TABLE generated_puzzles (
+  id SERIAL PRIMARY KEY,
+  grid_data JSONB NOT NULL,
+  clues_data JSONB NOT NULL,
+  topics TEXT[] NOT NULL,
+  difficulty INTEGER DEFAULT 1,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  expires_at TIMESTAMP DEFAULT (CURRENT_TIMESTAMP + INTERVAL '24 hours')
+);
+
+-- Sample data seeds
+INSERT INTO topics (name, description) VALUES 
+  ('Animals', 'Creatures from the animal kingdom'),
+  ('Science', 'Scientific terms and concepts'),
+  ('Geography', 'Places, landforms, and geographical features'),
+  ('Technology', 'Computing and technology terms'),
+  ('History', 'Historical events, people, and periods'),
+  ('Sports', 'Sports, games, and athletic activities');
+
+-- Sample words for Animals topic
+INSERT INTO words (word, length, difficulty_level, topic_id) VALUES 
+  ('DOG', 3, 1, 1),
+  ('CAT', 3, 1, 1),
+  ('ELEPHANT', 8, 2, 1),
+  ('TIGER', 5, 1, 1),
+  ('WHALE', 5, 2, 1),
+  ('BUTTERFLY', 9, 3, 1),
+  ('PENGUIN', 7, 2, 1),
+  ('GIRAFFE', 7, 2, 1);
+
+-- Sample clues for the words
+INSERT INTO clues (word_id, clue_text, difficulty) VALUES 
+  (1, 'Man''s best friend', 1),
+  (2, 'Feline pet that purrs', 1),
+  (3, 'Largest land mammal', 2),
+  (4, 'Striped big cat', 1),
+  (5, 'Largest marine mammal', 2),
+  (6, 'Colorful insect with wings', 3),
+  (7, 'Black and white Antarctic bird', 2),
+  (8, 'Tallest animal in the world', 2);