# marudham/wowgen architecture

> Architecture diagram of the GitHub repository marudham/wowgen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marudham/wowgen
- Repository: https://github.com/marudham/wowgen

## Overview

##### Project type & purpose (from tree + README)
This is a small **Java application/library** (single package `com.wowgen`) that appears to **generate or manipulate “words”** using:
- a **built-in English dictionary** (`dictionary.json`)
- **permutation / combinatorics logic** (`Permutation.java`)
- **domain objects** (`Word.java`)
- a **main generator/service** (`WOWGen.java`)
- an **application entry point** (`WOWGenApp.java`)

##### What to focus on
- **Runtime boundaries** (JVM process, classpath/libs, resource file)
- **Core functional components** (generator, dictionary loader, permutation engine, domain model)
- **Data flow** (dictionary JSON → in-memory structures → generator → output)
- **External dependencies** (Jackson jars for JSON parsing)

Don’t overthink distributed concerns (services, queues, DBs). Instead, separate the code into as many internal components as possible.

##### Main components (map directly to files)
Use the source files as the primary truth for component decomposition:

##### Application / Entry Point
- **`WOWGenApp.java`**: likely contains `public static void main(...)` and orchestrates the run.

##### Core Generator / Use-Case Layer
- **`WOWGen.java`**: the main “engine” coordinating dictionary usage + permutations to produce results.

##### Dictionary / Data Access Layer (but local)
- **`EnglishWordsDictionary.java`**: loads and queries dictionary words.
- Likely reads `dictionary.json` and exposes lookup/filter methods.

##### Algorithm / Utility Layer
- **`Permutation.java`**: combinatorics/permutation logic used by WOWGen.

##### Domain Model
- **`Word.java`**: representation of a word, maybe with metadata.

##### Local Resource
- **`src/com/wowgen/dictionary.json`** (and mirrored in `bin/...`): the embedded dictionary dataset.

##### Third-Party Libraries
- `lib/jackson-annotations-2.20.jar`
- `lib/jackson-core-2.20.0.jar`
- `lib/jackson-databind-2.20.0.jar`
- Used by `EnglishWordsDictionary` to parse JSON.

##### Build Output (optional)
- `bin/...`: compiled classes and copied resources (Eclipse-style output)

##### User/Invoker → WOWGenApp
- “Runs program / provides input args” (if any).

##### WOWGenApp → WOWGen
- “Constructs and calls generator”.

##### WOWGen → EnglishWordsDictionary
- “Queries dictionary / validates candidates”.

##### EnglishWordsDictionary → dictionary.json
- “Loads word list from bundled JSON resource”.

##### EnglishWordsDictionary → Jackson (ObjectMapper)
- “Parses JSON into in-memory structures”.

##### WOWGen → Permutation
- “Generates permutations / candidate strings”.

##### WOWGen ↔ Word
- “Creates/returns Word objects” or “operates on Word domain model”.

##### Architectural pattern(s) to call out
This project likely follows a simple layered separation:
- **Bootstrap/UI**: `WOWGenApp`
- **Core logic**: `WOWGen`, `Permutation`
- **Data source**: `EnglishWordsDictionary` reading a local resource
- **Domain model**: `Word`

- Actor: “User”
- External: “Local filesystem/classpath resource: dictionary.json”
- External: “Jackson libraries”

This clarifies: single JVM, local resource, no server.

Show:
- **JVM Process** boundary
- Inside: “WOWGenApp”, “WOWGen Engine”, “Dictionary Loader”, “Permutation Engine”, “Domain Model”
- Outside: “dictionary.json resource”, “Jackson JARs”

A more code-faithful view mapping **each `.java` file to a component** and drawing:
- `WOWGenApp` depends on `WOWGen`
- `WOWGen` depends on `EnglishWordsDictionary`, `Permutation`, `Word`
- `EnglishWordsDictionary` depends on `dictionary.json` and Jackson

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= System Context =========
    U["User / Invoker"]:::actor

    subgraph "Single JVM Process (WOWGen Java App/Library)"
        direction TB

        subgraph "Bootstrap / UI Layer"
            direction TB
            App["WOWGenApp (main / CLI runner)"]:::app
            Out["Stdout / Console Output"]:::io
        end

        subgraph "Core / Use-Case Layer"
            direction TB
            Gen["WOWGen (generation orchestrator)"]:::app
        end

        subgraph "Domain Model"
            direction TB
            Word["Word (domain object / value type)"]:::domain
        end

        subgraph "Algorithms / Utilities"
            direction TB
            Perm["Permutation (permutation engine)"]:::algo
        end

        subgraph "Dictionary / Local Data Access"
            direction TB
            Dict["EnglishWordsDictionary (dictionary repository / loader)"]:::data
            InMem["In-memory word list / index"]:::dataStore
        end
    end

    subgraph "Classpath Resources (Packaged with App)"
        direction TB
        DictJSON["dictionary.json (bundled resource)"]:::resource
        DictJSONBin["dictionary.json (bin copy)"]:::resource
    end

    subgraph "Third-Party Libraries (Classpath)"
        direction TB
        JacksonAnn["Jackson Annotations JAR"]:::external
        JacksonCore["Jackson Core JAR"]:::external
        JacksonDB["Jackson Databind JAR (ObjectMapper)"]:::external
    end

    %% ========= Relationships (vertical first) =========
    U -->|"runs"| App
    App -->|"constructs/calls"| Gen
    Gen -->|"returns/uses"| Word
    Gen -->|"generates_candidates"| Perm
    Gen -->|"queries/validates"| Dict
    App -->|"prints"| Out

    %% Dictionary load path
    Dict -.->|"loads_from_classpath"| DictJSON
    DictJSON -.->|"copied_to_output"| DictJSONBin
    Dict -->|"parses_JSON_with"| JacksonDB
    JacksonDB -->|"depends_on"| JacksonCore
    JacksonDB -->|"uses_annotations"| JacksonAnn
    Dict -->|"builds"| InMem
    InMem -->|"lookup/filter"| Dict

    %% Optional note-like link: permutation produces candidate strings for generator
    Perm -->|"candidate_strings"| Gen

    %% ========= Click Events =========
    click App "https://github.com/marudham/wowgen/blob/main/src/com/wowgen/WOWGenApp.java"
    click Gen "https://github.com/marudham/wowgen/blob/main/src/com/wowgen/WOWGen.java"
    click Dict "https://github.com/marudham/wowgen/blob/main/src/com/wowgen/EnglishWordsDictionary.java"
    click Perm "https://github.com/marudham/wowgen/blob/main/src/com/wowgen/Permutation.java"
    click Word "https://github.com/marudham/wowgen/blob/main/src/com/wowgen/Word.java"
    click DictJSON "https://github.com/marudham/wowgen/blob/main/src/com/wowgen/dictionary.json"
    click DictJSONBin "https://github.com/marudham/wowgen/blob/main/bin/com/wowgen/dictionary.json"
    click JacksonAnn "https://github.com/marudham/wowgen/blob/main/lib/jackson-annotations-2.20.jar"
    click JacksonCore "https://github.com/marudham/wowgen/blob/main/lib/jackson-core-2.20.0.jar"
    click JacksonDB "https://github.com/marudham/wowgen/blob/main/lib/jackson-databind-2.20.0.jar"

    %% Build output directory mapping (represented as a non-functional node for navigation)
    BinDir["bin/com/wowgen/ (compiled output dir)"]:::build
    click BinDir "https://github.com/marudham/wowgen/tree/main/bin/com/wowgen/"
    DictJSONBin -.->|"located_in"| BinDir

    %% ========= Styles =========
    classDef actor fill:#ffffff,stroke:#111827,stroke-width:2px,color:#111827;
    classDef app fill:#1d4ed8,stroke:#0b2f87,stroke-width:2px,color:#ffffff;
    classDef algo fill:#16a34a,stroke:#0f6b31,stroke-width:2px,color:#ffffff;
    classDef data fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#111827;
    classDef dataStore fill:#fbbf24,stroke:#b45309,stroke-width:2px,color:#111827;
    classDef domain fill:#7c3aed,stroke:#4c1d95,stroke-width:2px,color:#ffffff;
    classDef resource fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#111827;
    classDef external fill:#9ca3af,stroke:#4b5563,stroke-width:2px,color:#111827;
    classDef io fill:#e5e7eb,stroke:#6b7280,stroke-width:2px,color:#111827;
    classDef build fill:#cbd5e1,stroke:#475569,stroke-width:2px,color:#111827;
```
