# souhait0614/submarin-converter architecture

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

- Interactive diagram: https://gitdiagram.com/souhait0614/submarin-converter
- Repository: https://github.com/souhait0614/submarin-converter

## Overview

##### Project Type and Purpose
- This is a TypeScript‑based monorepo library (“submarin-converter”) that provides a core text‐conversion engine plus a variety of plug‑in modules (cjp, genhera, nomlish).
- It’s not a web app or microservice but a pluggable library targeting multiple JavaScript runtimes (Deno, Node, Bun).

##### File Structure Analysis
- Top‑level config: deno.json, deno.lock, package.json (npm publish), CI workflows (.github/workflows).
- /packages/core: The Converter class, plugin interface types, logger, constants.
- /packages/plugin‑…: Each plugin implements the Plugin interface, supplies conversion functions.
- /runtime‑tests: Three subdirs (bun, deno, node) verifying cross‑runtime compatibility using Vitest and native test runners.
- /scripts: Helpers to build/test and synchronize package versions across the monorepo.

##### Key Architectural Patterns
- Plugin architecture: Core defines a Plugin interface, dynamic loading / registration of plugins via a map of names to modules.
- Pipeline pattern: Converter.convert() runs a sequence of conversion functions chained in order.
- Polyglot packaging: Each package includes its own deno.json for Deno support and publishes via npm (package.json in root).

##### Main Components & Interactions
a. Converter Core
- Exposes Converter class and Plugin<T> interface.
- Maintains a registry of named plugins.
- Orchestrates conversion pipeline: input text → plugin1 → plugin2 → … → output text & detailed results.
b. Plugin Modules
- plugin-cjp, plugin-genhera, plugin-nomlish each implement Plugin and export convertFunctions (functions(text, option) ⇒ text).
- May include internal constants and helper modules (e.g., genhera/dict).
c. Runtime Adapters / Tests
- For each runtime (Deno, Node, Bun) there is a test harness invoking the core + selected plugins to validate behavior.
d. Build & Release
- CI pipelines run tests, build artifacts, and publish to npm/JSR.
- Scripts to keep version alignment and pre-test builds.

- PluginManager (register, resolve by name)
- ConversionPipeline (sequential execution of convertFunctions)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Top Level Config
    Config["Top-Level Config"]:::config
    click Config "https://github.com/souhait0614/submarin-converter/blob/master/deno.json"
    click Config "https://github.com/souhait0614/submarin-converter/blob/master/deno.lock"
    click Config "https://github.com/souhait0614/submarin-converter/blob/master/package.json"

    %% API Consumer
    AC["API Consumer"]:::consumer

    %% Core Converter and Subcomponents
    subgraph "Core Converter"
        direction TB
        CoreIndex["index.ts"]:::core
        CoreConverter["Converter.ts"]:::core
        CoreTypes["types.ts"]:::core
        CoreConstants["constants.ts"]:::core
        CoreLogger["logger.ts"]:::core
    end
    click CoreIndex "https://github.com/souhait0614/submarin-converter/blob/master/packages/core/src/index.ts"
    click CoreConverter "https://github.com/souhait0614/submarin-converter/blob/master/packages/core/src/Converter.ts"
    click CoreTypes "https://github.com/souhait0614/submarin-converter/blob/master/packages/core/src/types.ts"
    click CoreConstants "https://github.com/souhait0614/submarin-converter/blob/master/packages/core/src/constants.ts"
    click CoreLogger "https://github.com/souhait0614/submarin-converter/blob/master/packages/core/src/logger.ts"

    %% Plugin Modules
    CJP["Plugin-CJP"]:::plugin
    click CJP "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-cjp/src/index.ts"
    click CJP "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-cjp/src/dynamic.ts"
    click CJP "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-cjp/src/constants.ts"

    GEN["Plugin-Genhera"]:::plugin
    click GEN "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-genhera/src/index.ts"
    click GEN "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-genhera/src/dynamic.ts"
    click GEN "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-genhera/src/constants.ts"
    click GEN "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-genhera/src/genhera/index.ts"
    click GEN "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-genhera/src/genhera/dict/common.ts"
    click GEN "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-genhera/src/genhera/dict/kana.ts"

    NOM["Plugin-Nomlish"]:::plugin
    click NOM "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-nomlish/src/index.ts"
    click NOM "https://github.com/souhait0614/submarin-converter/blob/master/packages/plugin-nomlish/src/constants.ts"

    %% Test Suites
    subgraph "Test Suites"
        direction TB
        TS_Bun["Bun Test Suite"]:::test
        TS_Deno["Deno Test Suite"]:::test
        TS_Node["Node Test Suite"]:::test
    end
    click TS_Bun "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/bun/index.test.ts"
    click TS_Bun "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/bun/nomlish.test.ts"
    click TS_Bun "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/bun/vitest.config.ts"
    click TS_Deno "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/deno/index.test.ts"
    click TS_Deno "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/deno/nomlish.test.ts"
    click TS_Node "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/node/index.test.ts"
    click TS_Node "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/node/nomlish.test.ts"
    click TS_Node "https://github.com/souhait0614/submarin-converter/blob/master/runtime-tests/node/vitest.config.ts"

    %% CI/CD & Scripts
    subgraph "CI/CD & Scripts"
        direction TB
        CI["CI/CD Workflows"]:::cicd
        S1["pretest-build-packages.ts"]:::script
        S2["sync-packages-version.ts"]:::script
    end
    click CI "https://github.com/souhait0614/submarin-converter/blob/master/.github/workflows/ci.yml"
    click CI "https://github.com/souhait0614/submarin-converter/blob/master/.github/workflows/publish.yml"
    click S1 "https://github.com/souhait0614/submarin-converter/blob/master/scripts/pretest-build-packages.ts"
    click S2 "https://github.com/souhait0614/submarin-converter/blob/master/scripts/sync-packages-version.ts"

    %% Relationships
    Config --> AC
    AC -->|"invoke convert() with plugin names"| CoreIndex
    CoreIndex --> CoreConverter
    CoreConverter --> CoreTypes
    CoreConverter --> CoreConstants
    CoreConverter --> CoreLogger

    CoreIndex -->|"register & resolve"| CJP
    CoreIndex -->|"register & resolve"| GEN
    CoreIndex -->|"register & resolve"| NOM

    CJP -->|"convertFunctions"| CoreIndex
    GEN -->|"convertFunctions"| CoreIndex
    NOM -->|"convertFunctions"| CoreIndex

    TS_Bun -->|tests Core & Plugins| CoreIndex
    TS_Bun -->|tests Core & Plugins| CJP
    TS_Bun -->|tests Core & Plugins| GEN
    TS_Bun -->|tests Core & Plugins| NOM

    TS_Deno -->|tests Core & Plugins| CoreIndex
    TS_Deno -->|tests Core & Plugins| CJP
    TS_Deno -->|tests Core & Plugins| GEN
    TS_Deno -->|tests Core & Plugins| NOM

    TS_Node -->|tests Core & Plugins| CoreIndex
    TS_Node -->|tests Core & Plugins| CJP
    TS_Node -->|tests Core & Plugins| GEN
    TS_Node -->|tests Core & Plugins| NOM

    CI -->|runs tests & build & publish| CoreIndex
    CI -->|runs tests & build & publish| CJP
    CI -->|runs tests & build & publish| GEN
    CI -->|runs tests & build & publish| NOM
    CI -->|runs tests & build & publish| TS_Bun
    CI -->|runs tests & build & publish| TS_Deno
    CI -->|runs tests & build & publish| TS_Node

    CI --> S1
    CI --> S2

    %% Styles
    classDef consumer fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#CDE7FF,stroke:#1A63B8,color:#1A63B8;
    classDef plugin fill:#DCF8E3,stroke:#28A745,color:#28A745;
    classDef test fill:#FFE8C0,stroke:#D38B00,color:#D38B00;
    classDef cicd fill:#E6D6F1,stroke:#6F42C1,color:#6F42C1;
    classDef script fill:#F0E6F6,stroke:#5A32A3,color:#5A32A3;
    classDef config fill:#F5F5F5,stroke:#999999,color:#333333;
```
