iOS-Crossword-Engine

Project Overview

This project is a full-stack software system designed to algorithmically generate crossword puzzles and play them on a mobile device. It consists of a high-performance Python backend for generating grids and fitting words, and a native SwiftUI iOS frontend for rendering the puzzles into an interactive game.

System Architecture

The repository is divided into two distinct environments:

• Backend (Python): Handles all mathematical grid generation, template creation, and word-fitting logic. It utilizes Python's ProcessPoolExecutor for multi-core constraint backtracking, which is necessary to efficiently solve large 15x15 symmetrical grids.
• Frontend (SwiftUI): A native iOS application that reads the compiled JSON puzzles generated by the backend and provides the user interface for gameplay.

Dataset

The dictionary and clue database is built upon the albertxu/CrosswordQA dataset from Hugging Face, which contains over 6.7 million historical crossword clues and answers.

• The raw data is processed from train.csv.
• The cleaned and optimized data is stored locally in words.db (SQLite) for rapid querying during the constraint satisfaction process.

How to Use the Backend (Python)

Requirements

• Python 3.8+
• SQLite3

Execution Steps

1. Navigate to the Backend directory.
2. Generate Templates: Run the layout generators to create the initial empty grid structures. This outputs a templates.json file.

   python small_grid_generator.py
   # or for standard 15x15 grids
   python grid_generator.py

3. Build Database: If words.db is not present, compile it from the CSV source.

   python build_ru_db.py

4. Generate Puzzles: Execute the main engine to fill the templates with words using the database.

   python generator.py

   The compiled, playable puzzles will be exported as individual .json files to the output directory.

How to Use the Frontend (iOS)

Requirements

• macOS with Xcode 15+
• iOS 17.0+ Target

Execution Steps

1. Open Frontend/Crossword.xcodeproj in Xcode.
2. Move the generated .json puzzle files from the Python backend into the generated_puzzles folder within the Xcode project structure.
3. Select an iOS Simulator or connected iOS device.
4. Build and Run (Cmd + R).

Core Features

• Procedural Grid Generation: Supports asymmetrical small grids and standard 15x15 grids with rotational symmetry.
• Parallel Processing: The backend distributes the backtracking workload across CPU cores to reduce generation time.
• SwiftUI Integration: A modern, declarative UI parsing complex JSON game states into playable views.
• Filtering and Sorting: In-app capabilities to filter generated puzzles by size and symmetry type.