# mikeynap/hodoku architecture

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

- Interactive diagram: https://gitdiagram.com/mikeynap/hodoku
- Repository: https://github.com/mikeynap/hodoku

## Overview

##### Project Type and Purpose
- Hodoku is a standalone Java/Swing desktop application for generating, solving, training on, and analyzing standard Sudoku puzzles.
- It is packaged as a single JAR that runs on any Java 1.8+ runtime and supports two languages (English/German).

##### File‐Structure Analysis
- src/sudoku – all GUI classes (dialogs, panels, main window, event handlers)
- src/solver – solver engine interfaces and a suite of concrete solving strategies (Strategy Pattern + Factory)
- src/generator – puzzle‐generator classes, including factories and background threads for asynchronous generation
- src/intl – ResourceBundle properties for I18N (English/German)
- src/help – HTML user manual pages
- tests – a minimal smoke‐test entry point
- Other artifacts: templates.dat, showcase assets, build configs

##### README Insights
- Main purpose: Sudoku solver/generator/trainer/analyzer
- Highlights multi‐threaded background puzzle generation, a flexible “find all steps” feature, plugin‐like solver strategies, and extensive user preferences

##### Main Components
a. User Interface Layer (Blue)
- MainFrame / Main (entry point)
- Various Dialogs/Panels (e.g., AllStepsPanel, CellZoomPanel, ConfigDialog)
- Help Viewer
b. Controller/Coordinator (Light Blue)
- GuiState / Options classes
- Event dispatch/Action listeners in GUI components
- FileDrop, ListDragAndDrop helpers
c. Model Layer (Green)
- Sudoku, SudokuCell, Candidate, SudokuSet classes
- Entities representing the puzzle state and user annotations
d. Solver Engine (Orange)
- SudokuSolverFactory builds a SudokuSolver composed of multiple AbstractSolver implementations
- Individual Solvers (e.g., BruteForceSolver, FishSolver, WingSolver) following a Strategy Pattern
- SudokuStepFinder produces step-by-step explanation objects
e. Generator Engine (Orange)
- SudokuGeneratorFactory with GeneratorPattern implementations
- BackgroundGeneratorThread for asynchronous puzzle creation
f. Resource Manager / External Resources (Gray)
- I18N bundles in src/intl
- Help HTML pages

##### Component Interactions and Data Flows
- The UI layer raises user events → Controller passes requests to Model / Engines
- Generators and Solvers run (possibly in background threads) → update Model with new puzzle state or solution steps
- Controller/UI bind to Model changes → re-render panels/dialogs
- Resource Manager feeds localized strings and help pages into UI components
- ConfigDialog writes user preferences to disk; Options reads them on startup

##### Architectural Patterns & Principles
- MVC: UI components (View) separated from Model (Puzzle state) and Controllers
- Strategy Pattern: each solving technique implements a common interface; new strategies can be plugged in
- Factory Pattern: SolverFactory and GeneratorFactory hide concrete implementation choices
- Observer / Listener: UI updates in response to model or background‐thread events

## Diagram (Mermaid)

```mermaid
flowchart BT
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        MainEntry["Main (Entry Point)"]:::ui
        MainFrame["MainFrame"]:::ui
        subgraph "Dialogs & Panels"
            direction TB
            AllStepsPanel["AllStepsPanel"]:::ui
            CellZoomPanel["CellZoomPanel"]:::ui
            ConfigDialog["ConfigDialog"]:::ui
            GenerateProgress["GenerateSudokuProgressDialog"]:::ui
            SolverProgress["SolverProgressDialog"]:::ui
            ExtendedPrintDialog["ExtendedPrintDialog"]:::ui
            ExtendedPrintProgress["ExtendedPrintProgressDialog"]:::ui
            HistoryDialog["HistoryDialog"]:::ui
            PrintSolutionDialog["PrintSolutionDialog"]:::ui
            RestoreDialog["RestoreSavePointDialog"]:::ui
        end
        subgraph "Help Viewer"
            direction TB
            MyBrowserLauncher["MyBrowserLauncher"]:::ui
            HelpKeyboard["keyboard.html"]:::resource
            HelpKeyboardDe["keyboard_de.html"]:::resource
        end
    end

    %% Controller Layer
    subgraph "Controller / Coordinator"
        direction TB
        GuiState["GuiState"]:::controller
        Options["Options"]:::controller
        FileDrop["FileDrop"]:::controller
        ListDrag["ListDragAndDrop"]:::controller
        ListDragChange["ListDragAndDropChange"]:::controller
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        SudokuModel["Sudoku (Board Model)"]:::model
        SudokuCell["SudokuCell"]:::model
        Candidate["Candidate"]:::model
        SudokuSet["SudokuSet"]:::model
        SudokuSetBase["SudokuSetBase"]:::model
        SudokuSetShort["SudokuSetShort"]:::model
    end

    %% Solver Engine
    subgraph "Solver Engine" 
        direction TB
        SolverFactory["SudokuSolverFactory«Factory»"]:::engine
        AbstractSolver["AbstractSolver (Core Interface)"]:::engine
        StepFinder["SudokuStepFinder«Strategy»"]:::engine
        subgraph "Sample Strategies"
            direction TB
            BruteForce["BruteForceSolver"]:::engine
            Fish["FishSolver"]:::engine
            Wing["WingSolver"]:::engine
        end
    end

    %% Generator Engine
    subgraph "Generator Engine"
        direction TB
        GenFactory["SudokuGeneratorFactory«Factory»"]:::engine
        GenPattern["GeneratorPattern"]:::engine
        BackgroundThread["BackgroundGeneratorThread"]:::engine
        BackgroundEntry["BackgroundGenerator"]:::engine
    end

    %% Resources
    subgraph "Resource Manager / External"
        direction TB
        I18N["I18N Bundles"]:::resource
        Images["Image Icons"]:::resource
        Templates["templates.dat"]:::resource
    end

    %% Tests
    TestMain["Test Main (Smoke-Test)"]:::external

    %% Connections
    MainEntry --> MainFrame
    MainFrame --> AllStepsPanel
    MainFrame --> CellZoomPanel
    MainFrame --> ConfigDialog
    MainFrame --> GenerateProgress
    MainFrame --> SolverProgress
    MainFrame --> ExtendedPrintDialog
    MainFrame --> ExtendedPrintProgress
    MainFrame --> HistoryDialog
    MainFrame --> PrintSolutionDialog
    MainFrame --> RestoreDialog
    MainFrame --> MyBrowserLauncher

    MainFrame --> GuiState
    ConfigDialog --> Options

    MainFrame --> SolverFactory
    MainFrame --> GenFactory

    GuiState --> SudokuModel
    SolverFactory --> AbstractSolver
    AbstractSolver --> StepFinder
    AbstractSolver --> BruteForce
    AbstractSolver --> Fish
    AbstractSolver --> Wing

    GenFactory --> GenPattern
    GenPattern --> BackgroundThread
    BackgroundEntry --> BackgroundThread

    BackgroundThread --> SudokuModel
    StepFinder --> SudokuModel
    SudokuModel --> MainFrame

    MyBrowserLauncher --> HelpKeyboard
    MyBrowserLauncher --> HelpKeyboardDe

    ConfigDialog --> Templates

    MainEntry --> TestMain

    %% Resource feeds
    I18N --> MainFrame
    Images --> MainFrame

    %% Click Events
    click MainEntry "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/Main.java"
    click MainFrame "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/MainFrame.java"
    click AllStepsPanel "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/AllStepsPanel.java"
    click CellZoomPanel "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/CellZoomPanel.java"
    click ConfigDialog "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/ConfigDialog.java"
    click GenerateProgress "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/GenerateSudokuProgressDialog.java"
    click SolverProgress "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/SolverProgressDialog.java"
    click ExtendedPrintDialog "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/ExtendedPrintDialog.java"
    click ExtendedPrintProgress "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/ExtendedPrintProgressDialog.java"
    click HistoryDialog "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/HistoryDialog.java"
    click PrintSolutionDialog "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/PrintSolutionDialog.java"
    click RestoreDialog "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/RestoreSavePointDialog.java"
    click MyBrowserLauncher "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/MyBrowserLauncher.java"
    click GuiState "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/GuiState.java"
    click Options "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/Options.java"
    click FileDrop "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/FileDrop.java"
    click ListDrag "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/ListDragAndDrop.java"
    click ListDragChange "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/ListDragAndDropChange.java"
    click SudokuModel "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/Sudoku.java"
    click SudokuCell "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/SudokuCell.java"
    click Candidate "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/Candidate.java"
    click SudokuSet "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/SudokuSet.java"
    click SudokuSetBase "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/SudokuSetBase.java"
    click SudokuSetShort "https://github.com/mikeynap/hodoku/blob/master/src/sudoku/SudokuSetShort.java"
    click SolverFactory "https://github.com/mikeynap/hodoku/blob/master/src/solver/SudokuSolverFactory.java"
    click AbstractSolver "https://github.com/mikeynap/hodoku/blob/master/src/solver/AbstractSolver.java"
    click StepFinder "https://github.com/mikeynap/hodoku/blob/master/src/solver/SudokuStepFinder.java"
    click BruteForce "https://github.com/mikeynap/hodoku/blob/master/src/solver/BruteForceSolver.java"
    click Fish "https://github.com/mikeynap/hodoku/blob/master/src/solver/FishSolver.java"
    click Wing "https://github.com/mikeynap/hodoku/blob/master/src/solver/WingSolver.java"
    click GenFactory "https://github.com/mikeynap/hodoku/blob/master/src/generator/SudokuGeneratorFactory.java"
    click GenPattern "https://github.com/mikeynap/hodoku/blob/master/src/generator/GeneratorPattern.java"
    click BackgroundThread "https://github.com/mikeynap/hodoku/blob/master/src/generator/BackgroundGeneratorThread.java"
    click BackgroundEntry "https://github.com/mikeynap/hodoku/blob/master/src/generator/BackgroundGenerator.java"
    click I18N "https://github.com/mikeynap/hodoku/tree/master/src/intl/"
    click Images "https://github.com/mikeynap/hodoku/tree/master/src/img/"
    click Templates "https://github.com/mikeynap/hodoku/blob/master/src/templates.dat"
    click TestMain "https://github.com/mikeynap/hodoku/blob/master/src/tests/Main.java"

    %% Styles
    classDef ui fill:#add8e6,stroke:#000,stroke-width:1px
    classDef controller fill:#b0e0e6,stroke:#000,stroke-width:1px
    classDef model fill:#98fb98,stroke:#000,stroke-width:1px
    classDef engine fill:#ffa500,stroke:#000,stroke-width:1px
    classDef resource fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef external fill:#ffffff,stroke:#000,stroke-width:1px
```
