doc: Improve package architecture documentation and add options for managing dependencies

Author: kamiazya

docs/ts-graphviz/11-advanced-topics/02-package-architecture.md

@@ -17,7 +17,35 @@ description: Package architecture of ts-graphviz.
 
 - **`@ts-graphviz/react`**: Allows defining graphs using React's declarative UI paradigm, expressing DOT language models with JSX.
 
-## Dependency Graph
+## Exposing Internal Modules as Submodules
+
+**ts-graphviz** publishes some of its internal modules as submodules within the main package. Specifically, the following import paths are available to access these internal modules:
+
+- **`ts-graphviz/ast`** or **`@ts-graphviz/ast`**
+- **`ts-graphviz/adapter`** or **`@ts-graphviz/adapter`**
+
+This allows users to choose the module import style that best fits their project's needs. By using the `ts-graphviz/<module-name>` style, you can limit your dependencies to the `ts-graphviz` library itself, with internal packages (e.g., `@ts-graphviz/adapter`, `@ts-graphviz/ast`) being managed centrally by the `ts-graphviz` package. On the other hand, using the `@ts-graphviz/<module-name>` style enables you to manage dependencies on a per-module basis, allowing you to selectively install specific modules as needed.
+
+:::tip Managing Dependencies When Choosing Import Paths
+
+When using package managers that enforce strict dependency management (e.g., pnpm), the choice of import path can significantly impact how dependencies are handled. Consider the following points:
+
+- **Using `ts-graphviz/<module-name>` Style**:
+  - **Advantages**: Limits dependencies to the `ts-graphviz` library itself, with internal packages (e.g., `@ts-graphviz/adapter`, `@ts-graphviz/ast`) being managed centrally by the `ts-graphviz` package. This prevents dependency conflicts and ensures that stable versions recommended by the library are used.
+  - **Recommended Scenarios**: When you want to minimize dependencies or when the internal packages managed by `ts-graphviz` do not have specific version requirements.
+
+- **Using `@ts-graphviz/<module-name>` Style**:
+  - **Advantages**: Allows you to manage dependencies on a per-module basis, installing only the specific modules you need, which can help keep your application lightweight.
+  - **Caveats**: Requires you to manage internal dependencies (e.g., `@ts-graphviz/adapter`, `@ts-graphviz/ast`) separately within your package manager. This can complicate version management.
+  - **Recommended Scenarios**: When you need to use specific modules only or require detailed control over your dependencies.
+
+**Summary**:
+- If you prefer **simple dependency management**, use the `ts-graphviz/<module-name>` style.
+- If you require **fine-grained control over dependencies** or only need specific modules, opt for the `@ts-graphviz/<module-name>` style.
+
+This approach allows you to manage dependencies in a way that best suits your project's requirements.
+:::
+
 
 The relationships between packages can be visualized as follows:
 

i18n/ja/docusaurus-plugin-content-docs/current/ts-graphviz/11-advanced-topics/02-package-architecture.md

@@ -17,6 +17,37 @@ description: ts-graphvizのパッケージアーキテクチャ
 
 - **`@ts-graphviz/react`**: Reactの宣言的UIパラダイムを使用してグラフを定義することを可能にし、JSXでDOT言語モデルを表現します。
 
+## サブモジュールとしての内部モジュールの公開
+
+**ts-graphviz** パッケージは、内部モジュールの一部をサブモジュールとして公開しています。具体的には、以下のインポートパスを利用して内部モジュールにアクセスできます：
+
+- **`ts-graphviz/ast`** または **`@ts-graphviz/ast`**
+- **`ts-graphviz/adapter`** または **`@ts-graphviz/adapter`**
+
+これにより、ユーザーはプロジェクトのニーズに応じて柔軟にモジュールを選択できます。
+`ts-graphviz/<モジュール名>` スタイルを使用することで、`ts-graphviz` ライブラリ自体のみに依存関係を絞り、内部パッケージ（例: `@ts-graphviz/adapter` や `@ts-graphviz/ast`）のバージョンは `ts-graphviz` パッケージによって一元管理されます。
+一方、`@ts-graphviz/<モジュール名>` スタイルを使用すると、必要な機能ごとに個別に依存関係を管理でき、特定のモジュールのみを選択的にインストールすることが可能です。
+
+:::tip インポートパス選択時の依存関係管理
+
+依存関係を厳密に管理するパッケージマネージャー（例: pnpm）を使用する場合、インポートパスの選択が依存関係の管理に大きな影響を与えることがあります。以下のポイントを参考にしてください：
+
+- **`ts-graphviz/<モジュール名>` スタイルの利用**:
+  - **利点**: `ts-graphviz` ライブラリ自体のみに依存関係を絞ることができ、内部パッケージ（例: `@ts-graphviz/adapter` や `@ts-graphviz/ast`）のバージョンは `ts-graphviz` パッケージによって一元管理されます。これにより、依存関係の衝突を防ぎ、ライブラリの推奨に基づいた安定したバージョンが使用されます。
+  - **推奨シナリオ**: 依存関係を最小限に抑えたい場合や、`ts-graphviz` が内部で管理する依存パッケージに特別なバージョン要件がない場合。
+
+- **`@ts-graphviz/<モジュール名>` スタイルの利用**:
+  - **利点**: 必要な機能ごとに個別に依存関係を管理できるため、特定のモジュールのみを選択的にインストールし、アプリケーションの軽量化が図れます。
+  - **注意点**: パッケージマネージャーで内部依存パッケージ（例: `@ts-graphviz/adapter` や `@ts-graphviz/ast`）も個別に管理する必要があります。これにより、依存関係のバージョン管理が複雑になる可能性があります。
+  - **推奨シナリオ**: 特定のモジュールのみを使用したい場合や、依存関係の詳細な管理が必要な場合。
+
+**まとめ**:
+- **シンプルな依存関係管理**を希望する場合は、`ts-graphviz/<モジュール名>` スタイルを使用してください。
+- **細かな依存関係の管理**や、特定のモジュールのみを利用したい場合は、`@ts-graphviz/<モジュール名>` スタイルを選択してください。
+
+これにより、プロジェクトのニーズに最適な依存関係管理が可能となります。
+:::
+
 ## 依存関係グラフ
 
 パッケージ間の関係は以下のように視覚化できます：