# ashleyzhang216/crossword-gen architecture

> Architecture diagram of the GitHub repository ashleyzhang216/crossword-gen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashleyzhang216/crossword-gen
- Repository: https://github.com/ashleyzhang216/crossword-gen

## Overview

##### Project Type and Purpose
- This is a command-line utility for generating crossword puzzles.
- It takes the user’s specifications (such as grid dimensions, grid contents, and word dictionary) and generates a crossword puzzle using a constrained satisfaction problem (CSP) approach.
- The README explains that the core algorithm uses techniques like the AC-3 algorithm for arc consistency and backtracking for assigning words to slots.
- Essentially, the project is modular with clearly separated components responsible for CLI handling, puzzle generation (crossword), CSP solving, word domain management, and supporting utilities as well as testing.

##### Analyzing the File Structure
- Top-level directories:
- .github: Contains CI/CD configuration files.
- assets: Contains images/gifs for live demos and documentation.
- src: Contains the source code organized into various domains:
- cli: Entry point and user interface for the command-line utility (cw_gen.cpp, cw_gen.h).
- common: Shared data types and base functionality used across modules.
- crossword: Implements the crossword specific logic (grid representation, puzzle structure, etc.).
- cw_csp: Contains the implementation for the constraint satisfaction problem solver (AC-3, backtracking).
- cw_timetracker and cw_tree: Likely provide additional utility or tracking features within the puzzle generation process.
- word_domain: Manages word dictionary data types and functionality.
- data: Holds dictionary files and other dataset resources (JSON files, raw text files, and supporting scripts to build/prepare the datasets).
- lib, utils, and scripts: Provide libraries (e.g., JSON parsing and command-line options), helper functions, and additional support utilities.
- test: Contains test cases and drivers using the Catch2 framework to validate the functionality of different modules.

##### Main Components
A. CLI Component (src/cli):
- The starting point “cw_gen” that parses command-line arguments.
- Responsible for handling user input, options (like size, grid contents, dictionary selection, verbosity, progress bar), and triggering the generation process.

B. Crossword Module (src/crossword):
- Manages crossword grid data structures, tile representation, and overall puzzle organization.
- Interfaces with the CSP module and word domain module to acquire and place words.

C. CSP Solver Module (src/cw_csp):
- Implements the core CSP algorithms (AC-3 algorithm for arc consistency, and backtracking search) to solve the generated crossword puzzle.
- Receives parameters (variable definitions based on grid intersections) from the crossword module and returns a consistent assignment if successful.

D. Word Domain Module (src/word_domain):
- Manages the word lists/dictionaries.
- Selects an appropriate set of words based on dictionary size options (small, medium, large, etc.), and supplies them to the CSP solver.

E. Utilities and Common Functionality:
- Located in src/common, src/utils, and src/lib. These provide shared data types, logging, helper functions, and container implementations.
- They are used across the CLI, crossword, CSP, and word domain modules to promote code reuse and maintain consistency.

F. Data Resources:
- Located in src/data, these files (JSON and raw text files) are integrated into the system to provide input dictionaries and other parameters needed for crossword generation.
- There are also scripts to build or preprocess the datasets.

G. Test Suite:
- Contains unit tests and drivers under the test directory.
- Demonstrates the modularity and correctness of each component using the Catch2 framework.

##### Relationships and Interactions Between Components
- The CLI parses options and then passes control along to the Crossword Module.
- The Crossword Module constructs the puzzle’s structure and populates the CSP variables, then delegates the solving to the CSP Solver.
- The CSP Solver uses data from the Word Domain Module (which in turn pulls from the dictionary files in Data Resources) to attempt a solution using AC-3 and backtracking.
- Utility modules (common, utils, lib) are used throughout the flow for support tasks like logging, container manipulations, and configuration handling.
- The test suite interfaces with these modules to ensure each component functions correctly and in concert.

##### Important Architectural Patterns and Design Principles
- Modularity: Each component exists in its own directory with a clear responsibility (e.g., CLI, crossword generation, CSP solving).
- Separation of Concerns: Distinct separation between input processing (CLI), business logic (crossword and CSP modules), and auxiliary functions (utilities, common functions).
- Reusability: Shared libraries and utilities enforce code reusability and easier maintenance.
- Iterative Processing: The CSP solving process using AC-3 and backtracking demonstrates iterative constraint checking and solution search.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer: CLI Component
    subgraph "CLI Component"
        CLI1["cw_gen.cpp"]:::cli
        CLI2["cw_gen.h"]:::cli
        CLI3["cw_gen_data_types.h"]:::cli
    end

    %% Core Module: Crossword Engine
    subgraph "Crossword Module"
        CW1["crossword.cpp"]:::crossword
        CW2["crossword.h"]:::crossword
    end

    %% Core Module: CSP Solver
    subgraph "CSP Solver Module"
        CSP1["cw_csp.cpp"]:::csp
        CSP2["cw_csp.h"]:::csp
    end

    %% Core Module: Word Domain Management
    subgraph "Word Domain Module"
        WD1["word_domain.cpp"]:::word
        WD2["word_domain.h"]:::word
    end

    %% Supporting: Utilities & Common Functionality
    subgraph "Utilities & Common"
        COM1["common_data_types.cpp"]:::util
        COM2["common_data_types.h"]:::util
        UTILS["utils (cw_functions.hpp, json.hpp, cxxopts.hpp)"]:::util
        LIB["lib"]:::util
    end

    %% External Data: Data Resources
    subgraph "Data Resources"
        DATA["data (JSON, raw, scripts)"]:::data
    end

    %% Test Suite
    subgraph "Test Suite"
        TEST["test (Catch2 and test drivers)"]:::test
    end

    %% Relationships and Data Flow
    CLI1 -->|"initiates"| CW1
    CW1 -->|"sets constraints"| CSP1
    CW1 -->|"retrieves words"| WD1
    CSP1 -->|"validates domain"| WD1
    WD1 -->|"supplied by"| DATA

    %% Utilities support across modules (dashed arrows)
    CLI1 --- UTILS
    CW1 --- UTILS
    CSP1 --- UTILS
    WD1 --- UTILS

    %% Test validations (dashed arrows)
    TEST --- CLI1
    TEST --- CW1
    TEST --- CSP1
    TEST --- WD1

    %% Click Events for CLI Files
    click CLI1 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/cli/cw_gen.cpp"
    click CLI2 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/cli/cw_gen.h"
    click CLI3 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/cli/cw_gen_data_types.h"

    %% Click Events for Crossword Module Files
    click CW1 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/crossword/crossword.cpp"
    click CW2 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/crossword/crossword.h"

    %% Click Events for CSP Solver Module Files
    click CSP1 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/cw_csp/cw_csp.cpp"
    click CSP2 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/cw_csp/cw_csp.h"

    %% Click Events for Word Domain Module Files
    click WD1 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/word_domain/word_domain.cpp"
    click WD2 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/word_domain/word_domain.h"

    %% Click Events for Utilities and Common
    click COM1 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/common/common_data_types.cpp"
    click COM2 "https://github.com/ashleyzhang216/crossword-gen/blob/main/src/common/common_data_types.h"
    click UTILS "https://github.com/ashleyzhang216/crossword-gen/tree/main/src/utils"
    click LIB "https://github.com/ashleyzhang216/crossword-gen/tree/main/src/lib"

    %% Click Event for Data Resources
    click DATA "https://github.com/ashleyzhang216/crossword-gen/tree/main/src/data"

    %% Click Event for Test Suite
    click TEST "https://github.com/ashleyzhang216/crossword-gen/tree/main/test"

    %% Styles
    classDef cli fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef crossword fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef csp fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef word fill:#f94144,stroke:#000,stroke-width:2px;
    classDef util fill:#577590,stroke:#000,stroke-width:2px;
    classDef data fill:#277da1,stroke:#000,stroke-width:2px;
    classDef test fill:#8d99ae,stroke:#000,stroke-width:2px;
```
