# otoneko1102/closewords architecture

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

- Interactive diagram: https://gitdiagram.com/otoneko1102/closewords
- Repository: https://github.com/otoneko1102/closewords

## Overview

##### Project type and purpose
- This is an open-source Node.js library (npm package) named “closewords.”
- Purpose: given a target word (with optional pronunciation) and a list of candidate words, it returns the most similar words by character‐by‐character and phonetic similarity. It supports Japanese (including kanji) and uses morphological analysis under the hood.

##### File structure
- Top-level:
- package.json (metadata, dependencies)
- index.js / index.d.ts (public API entry point + TypeScript definitions)
- README.md (usage & change log)
- examples/ (demo scripts)
- src/worker.js (worker thread code)
- lib/:
– dict/ (compressed dictionary data files .dat.gz)
– src/ (supporting JS modules: isAlphabetOnly.js, toHepburn.js)
- Patterns & architectural choices:
- Single-process entrypoint delegating heavy work to worker_threads
- Data-driven design: morphological analysis using pre-packaged dictionary files
- Modular utility code for phonetic conversion and filtering

##### Key insights from README
- Core function: closeWords(word, candidates, raw?) → Promise of results
- Uses: worker_threads to parallelize morphological analysis
- Algorithms employed: Levenshtein, Jaro-Winkler, phonetic (Hepburn) completion
- Performance note: dictionary size and worker overhead

##### Main components & interactions
a. Components
1. Consumer (your application or example script)
2. Library API (index.js)
3. Worker Pool (worker_threads running src/worker.js)
4. Dictionary Data Loader (lib/dict/*.gz)
5. Utility Modules (lib/src/toHepburn.js, isAlphabetOnly.js)
6. Similarity Engine (fast-levenshtein, jaro-winkler algorithms)
b. Relationships & Data Flow
1. Consumer → calls Library API (closeWords)
2. Library API → spawns Worker(s)
3. Worker(s) → load Dictionary Data (decompress .dat.gz)
4. Worker(s) → perform morphological analysis on input and candidates
5. Worker(s) → use Utility Modules for phonetic conversion/filtering
6. Worker(s) → compute similarity scores (Similarity Engine)
7. Worker(s) → return scored results to Library API
8. Library API → resolve Promise to Consumer
c. Architectural patterns & principles
- Concurrency via worker_threads to offload CPU-bound analysis
- Separation of concerns: API layer vs. worker logic vs. data
- Data-driven processing: dictionary files abstracted behind a loader
- Modular design for extensibility (swap dictionary, add algorithms)
d. Technologies & frameworks
- Node.js (Worker Threads)
- fast-levenshtein, jaro-winkler (npm modules)
- Gzip-compressed dictionary files (.gz)
- JavaScript modules and TypeScript definitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer Application"
        EN["examples/en.js"]:::public
        JA["examples/ja.js"]:::public
    end

    subgraph "Library API"
        API["Library API (closeWords)"]:::public
    end

    subgraph "Worker Pool"
        WP1["Worker Thread"]:::internal
        WP2["Worker Thread"]:::internal
    end

    subgraph "Dictionary Store"
        Dict["Dictionary Data Loader (.dat.gz)"]:::data
    end

    subgraph "Utility Modules"
        ISO["isAlphabetOnly.js"]:::internal
        HEP["toHepburn.js"]:::internal
    end

    subgraph "Similarity Engine (third-party)"
        Lev["fast-levenshtein"]:::thirdParty
        Jaro["jaro-winkler"]:::thirdParty
    end

    EN -->|"calls closeWords"| API
    JA -->|"calls closeWords"| API
    API -->|"spawn Worker"| WP1
    API -->|"spawn Worker"| WP2

    WP1 -->|"load Dictionary"| Dict
    WP2 -->|"load Dictionary"| Dict

    WP1 -->|"use Utils"| ISO
    WP1 -->|"use Utils"| HEP
    WP2 -->|"use Utils"| ISO
    WP2 -->|"use Utils"| HEP

    WP1 -->|"compute similarity"| Lev
    WP1 -->|"compute similarity"| Jaro
    WP2 -->|"compute similarity"| Lev
    WP2 -->|"compute similarity"| Jaro

    WP1 -->|"return results"| API
    WP2 -->|"return results"| API
    API -->|"resolve Promise"| EN
    API -->|"resolve Promise"| JA

    click EN "https://github.com/otoneko1102/closewords/blob/main/examples/en.js"
    click JA "https://github.com/otoneko1102/closewords/blob/main/examples/ja.js"
    click API "https://github.com/otoneko1102/closewords/blob/main/index.js"
    click WP1 "https://github.com/otoneko1102/closewords/blob/main/src/worker.js"
    click WP2 "https://github.com/otoneko1102/closewords/blob/main/src/worker.js"
    click Dict "https://github.com/otoneko1102/closewords/blob/main/lib/dict/*.dat.gz"
    click ISO "https://github.com/otoneko1102/closewords/blob/main/lib/src/isAlphabetOnly.js"
    click HEP "https://github.com/otoneko1102/closewords/blob/main/lib/src/toHepburn.js"
    click Lev "https://github.com/otoneko1102/closewords/blob/main/package.json"
    click Jaro "https://github.com/otoneko1102/closewords/blob/main/package.json"

    classDef public fill:#cce5ff,stroke:#003366
    classDef internal fill:#d4edda,stroke:#155724
    classDef data fill:#fff3cd,stroke:#856404
    classDef thirdParty fill:#f8d7da,stroke:#721c24,stroke-dasharray:5 5
```
