# illusionmods/kkmanager architecture

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

- Interactive diagram: https://gitdiagram.com/illusionmods/kkmanager
- Repository: https://github.com/illusionmods/kkmanager

## Overview

1. **Overall shape**
   - KKManager is a multi-project .NET desktop solution centered on a WinForms-style GUI.
   - The main application is `KKManager`, with reusable domain and UI infrastructure in `KKManager.Core`.
   - Two side projects extend the toolchain: `KKManager.Updater` handles online update operations, and `StandaloneUpdater` is a separate bootstrap executable for replacing files outside the main process.

2. **Top-level application shell**
   - `KKManager/Program.cs` starts the desktop app and opens `MainWindow`.
   - The main window hosts the primary navigation into “content” areas for cards, plugins, sideloader mods, and sardine mods.
   - Most user actions flow through modal dialogs and tool windows such as path selection, rename cards, log viewer, and property inspectors.

3. **Core UI and shared controls**
   - `KKManager.Core` contains reusable WinForms controls and dialogs, including logging and process-wait UI.
   - These are shared across the main app and updater so the UI behavior is consistent for progress reporting, waiting on external processes, and logging.
   - The `Controls`, `Util`, and `Windows`-style components act as the presentation-layer foundation.

4. **File-system centered domain model**
   - The app is built around local game folders, installed mods, plugins, and card files rather than a server-backed database.
   - Common abstractions like `IFileInfoBase` and `ModInfoBase` model discovered files and installed assets.
   - `PathTools`, `InstallDirectoryHelper`, and related utilities indicate that path discovery and filesystem normalization are central concerns.

5. **Game content parsing**
   - A large portion of `KKManager.Core/Data/Cards` is devoted to parsing different card formats for multiple Illusion games.
   - Each game family has its own subfolder and model types: `AI`, `KK`, `KKS`, `EC`, `HC`, `RG`, `SVS`, `AC`.
   - `CardLoader`, `Card`, `UnknownCard`, and `CardType` provide the common entry point and type discrimination, while per-game classes deserialize the game-specific payloads.

6. **Installed mod and plugin inventory**
   - `Data/Zipmods`, `Data/Plugins`, and `Data/Sardines` represent the supported installed-package formats the app can browse and inspect.
   - Sideloader mods have manifest/version handling, migration metadata, and custom version comparison logic.
   - Plugin metadata and “sardine” mod metadata are loaded separately, then surfaced in the main content windows and property viewers.

7. **External-data extraction**
   - `Data/ExtData` parses embedded side-loaded metadata using pluggable deserializers.
   - This is the boundary where raw archive or file content is converted into richer mod metadata.
   - The design suggests the app can inspect files without fully installing them, which is important for browsing and update detection.

8. **Update pipeline**
   - `KKManager.Updater` is a distinct subsystem responsible for discovering, downloading, and applying updates.
   - `UpdateSourceManager` coordinates multiple backend source types: FTP, Mega, S3, torrent, and ZIP-based update sources.
   - The update flow is modeled in `Data/UpdateInfo`, `UpdateItem`, `UpdateTask`, and downloader status types, then executed through `UpdateDownloadCoordinator`.

9. **Installation and repair actions**
   - `Functions/ModInstaller`, `ZipmodTools`, and `SelfUpdater` show that the app can not only identify updates but also apply them locally.
   - `DeleteFileUpdateItem` and migration-related types imply the updater can handle destructive or transform-style changes, not just additive downloads.
   - `ModInstaller` is the bridge between discovered update content and changes to the game directory.

10. **User-facing tool windows**
   - The main app includes dedicated windows for browsing cards, sideloader mods, plugins, and sardine mods.
   - Property tool windows provide type-specific inspection, with separate viewers for cards, plugins, sardines, and generic objects.
   - This is where parsed metadata from the core layer becomes actionable UI.

11. **Modpack tooling**
   - `KKManager/ModpackTool` is a separate in-app utility for creating, editing, and verifying modpack-related structures.
   - It includes processors, validators, manifest editors, and verification windows.
   - This subsystem operates on zipmod entry data and configuration objects, so it sits between raw archive contents and update/distribution metadata.

12. **SB3UGS integration**
   - `KKManager.SB3UGS` appears to be an adapter or initializer layer for the bundled SB3UGS tooling in `src/libs/SB3UGS`.
   - The bundled binaries and plugin XML suggest the app can reuse external utility executables for game asset or model-related operations.
   - This is a clearly separated integration boundary rather than a core dependency of the main manager logic.

13. **Cross-cutting concerns**
   - Localization is pervasive: most UI forms have `.resx` files for Japanese, Russian, Simplified Chinese, and Traditional Chinese.
   - `LanguageManager`, `Resources`, and generated resource classes indicate the UI text and some dialog content are localized.
   - Logging is also first-class, with shared log controls and log viewer windows.

14. **Build, release, and validation**
   - The solution includes CI via GitHub Actions, a release script, and a small `Tests` project.
   - The tests currently focus on version comparison behavior, which is important because update selection depends on correct semver-like ordering.
   - `PortableSettingsProvider` is a small support project, likely for user settings persistence across installs.

15. **How data flows through the system**
   - The typical flow is: detect local game/install paths → scan files on disk → parse cards/mods/plugins into domain models → present them in the UI → optionally fetch updates from remote sources → download/apply changes → refresh the local inventory view.
   - The architecture is therefore centered on local filesystem state plus remote update metadata, with the UI as a thin orchestrator over parsing, update, and install services.

Main entry points: [`src/KKManager/Windows/MainWindow.cs`](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager/Windows/MainWindow.cs) (Main Window), [`src/KKManager.Core/Data`](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data) (Mod Metadata), [`src/KKManager/Windows/ToolWindows`](https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/ToolWindows) (Tool Windows), [`src/KKManager.Core/Functions`](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Functions) (File Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Main app"]
  node_node_program(("Program<br/>entrypoint<br/>[Program.cs]"))
  node_node_mainwindow["Main Window<br/>shell<br/>[MainWindow.cs]"]
  node_node_content["Content Views<br/>content-ui"]
  node_node_tools_ui["Tool Windows<br/>inspection-ui"]
  node_node_dialogs["Dialogs<br/>action-ui"]
end

subgraph group_grp_core["Core library"]
  node_node_core_ui["Shared UI<br/>winforms-infra<br/>[Controls]"]
  node_node_core_files["File Tools<br/>filesystem-infra<br/>[Functions]"]
  node_node_core_cards[("Card Parsers<br/>content-model<br/>[Cards]")]
  node_node_core_mods["Mod Metadata<br/>inventory-model<br/>[Data]"]
  node_node_core_extdata["Ext Data<br/>metadata-extraction<br/>[ExtData]"]
  node_node_localization["Localization<br/>resources<br/>[Properties]"]
end

subgraph group_grp_updater["Updater"]
  node_node_updaterprog(("Updater App<br/>entrypoint<br/>[KKManager.Updater]"))
  node_node_sources["Update Sources<br/>source-adapters<br/>[Sources]"]
  node_node_updateflow["Update Flow<br/>update-model<br/>[Data]"]
  node_node_downloader["Download Coordinator<br/>download-engine<br/>[Downloader]"]
end

subgraph group_grp_tools["Tooling"]
  node_node_modpacktool["Modpack Tool"]
end

subgraph group_grp_support["Support"]
  node_node_settings["Settings<br/>persistence"]
  node_node_tests["Tests<br/>test-suite"]
  node_node_sb3ugs["SB3UGS<br/>external-tooling"]
end

node_node_program -->|"opens"| node_node_mainwindow
node_node_mainwindow -->|"navigates to"| node_node_content
node_node_mainwindow -->|"opens"| node_node_tools_ui
node_node_mainwindow -->|"uses"| node_node_dialogs
node_node_content -->|"reads"| node_node_core_cards
node_node_content -->|"reads"| node_node_core_mods
node_node_tools_ui -->|"inspects"| node_node_core_mods
node_node_tools_ui -->|"inspects"| node_node_core_cards
node_node_tools_ui -->|"shares"| node_node_core_ui
node_node_dialogs -->|"operates on"| node_node_core_files
node_node_modpacktool -->|"processes"| node_node_core_mods
node_node_modpacktool -->|"verifies"| node_node_core_files
node_node_updaterprog -->|"loads"| node_node_sources
node_node_updaterprog -->|"models"| node_node_updateflow
node_node_updaterprog -->|"executes"| node_node_downloader
node_node_downloader -->|"pulls from"| node_node_sources
node_node_downloader -->|"updates"| node_node_updateflow
node_node_sources -->|"applies to"| node_node_core_files
node_node_core_mods -->|"parses with"| node_node_core_extdata
node_node_core_ui -->|"localizes with"| node_node_localization
node_node_mainwindow -->|"localizes with"| node_node_localization
node_node_core_files -->|"integrates with"| node_node_sb3ugs
node_node_tests -->|"checks"| node_node_core_mods
node_node_settings -->|"persists"| node_node_mainwindow

click node_node_program "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager/Program.cs"
click node_node_mainwindow "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager/Windows/MainWindow.cs"
click node_node_content "https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/Content"
click node_node_tools_ui "https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/ToolWindows"
click node_node_dialogs "https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/Dialogs"
click node_node_modpacktool "https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/ModpackTool"
click node_node_updaterprog "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater"
click node_node_sources "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater/Sources"
click node_node_updateflow "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater/Data"
click node_node_downloader "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater/Downloader"
click node_node_core_ui "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Controls"
click node_node_core_files "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Functions"
click node_node_core_cards "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data/Cards"
click node_node_core_mods "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data"
click node_node_core_extdata "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data/ExtData"
click node_node_localization "https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Properties"
click node_node_settings "https://github.com/illusionmods/kkmanager/tree/master/src/PortableSettingsProvider"
click node_node_tests "https://github.com/illusionmods/kkmanager/tree/master/src/Tests"
click node_node_sb3ugs "https://github.com/illusionmods/kkmanager/tree/master/src/libs/SB3UGS"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_program,node_node_mainwindow,node_node_content,node_node_tools_ui,node_node_dialogs toneBlue
class node_node_core_ui,node_node_core_files,node_node_core_cards,node_node_core_mods,node_node_core_extdata,node_node_localization toneAmber
class node_node_updaterprog,node_node_sources,node_node_updateflow,node_node_downloader toneMint
class node_node_modpacktool toneRose
class node_node_settings,node_node_tests,node_node_sb3ugs toneIndigo
```

## Components

### Main app

Primary desktop shell and user-facing content windows.

- [Program](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager/Program.cs): entrypoint · Starts the desktop application and opens the main window. · `src/KKManager/Program.cs`
- [Main Window](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager/Windows/MainWindow.cs): shell · Primary WinForms shell and navigation hub. · `src/KKManager/Windows/MainWindow.cs`
- [Content Views](https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/Content): content-ui · Browsers for cards, plugins, sideloader mods, and sardine mods. · `src/KKManager/Windows/Content`
- [Tool Windows](https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/ToolWindows): inspection-ui · Log viewer and property inspectors for parsed domain objects. · `src/KKManager/Windows/ToolWindows`
- [Dialogs](https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/Windows/Dialogs): action-ui · Path selection, rename, and other task-focused dialogs. · `src/KKManager/Windows/Dialogs`

### Core library

Shared parsing, filesystem, and UI infrastructure.

- [Shared UI](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Controls): winforms-infra · Reusable controls, loading UI, process wait UI, and log display. · `src/KKManager.Core/Controls`
- [File Tools](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Functions): filesystem-infra · Path discovery, install directory handling, process helpers, and installer actions. · `src/KKManager.Core/Functions`
- [Card Parsers](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data/Cards): content-model · Common card abstractions plus per-game parsers for multiple Illusion game families. · `src/KKManager.Core/Data/Cards`
- [Mod Metadata](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data): inventory-model · Sideloader, plugin, and sardine loaders for installed-package browsing. · `src/KKManager.Core/Data`
- [Ext Data](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Data/ExtData): metadata-extraction · Pluggable deserializers for embedded sideloader metadata. · `src/KKManager.Core/Data/ExtData`
- [Localization](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Core/Properties): resources · Language manager and localized resource sets used across UI. · `src/KKManager.Core/Properties`

### Updater

Remote update discovery, download, and apply pipeline.

- [Updater App](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater): entrypoint · Standalone updater runtime for fetching and applying updates. · `src/KKManager.Updater`
- [Update Sources](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater/Sources): source-adapters · FTP, Mega, S3, torrent, and ZIP-backed update source implementations. · `src/KKManager.Updater/Sources`
- [Update Flow](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater/Data): update-model · UpdateInfo, UpdateItem, UpdateTask, and download status coordination. · `src/KKManager.Updater/Data`
- [Download Coordinator](https://github.com/illusionmods/kkmanager/blob/master/src/KKManager.Updater/Downloader): download-engine · Orchestrates source selection, transfers, and download state. · `src/KKManager.Updater/Downloader`

### Tooling

In-app utilities and bootstrap executables.

- [Modpack Tool](https://github.com/illusionmods/kkmanager/tree/master/src/KKManager/ModpackTool): utility · In-app workflow for creating, editing, and verifying modpack data. · `src/KKManager/ModpackTool`

### Support

Build, tests, settings, and bundled external tooling.

- [Settings](https://github.com/illusionmods/kkmanager/tree/master/src/PortableSettingsProvider): persistence · Portable settings and application configuration persistence. · `src/PortableSettingsProvider`
- [Tests](https://github.com/illusionmods/kkmanager/tree/master/src/Tests): test-suite · Version comparison coverage for update selection logic. · `src/Tests`
- [SB3UGS](https://github.com/illusionmods/kkmanager/tree/master/src/libs/SB3UGS): external-tooling · Bundled external asset/tool executables and initializer bridge. · `src/libs/SB3UGS`

## Connections

- Program → Main Window: opens · Application startup creates the primary shell.
- Main Window → Content Views: navigates to · Main shell hosts the content browsing views.
- Main Window → Tool Windows: opens · Main shell launches inspection and log tool windows.
- Main Window → Dialogs: uses · Main shell invokes modal dialogs for focused actions.
- Content Views → Card Parsers: reads · Content windows render parsed card inventories.
- Content Views → Mod Metadata: reads · Content windows render installed mod and plugin inventories.
- Tool Windows → Mod Metadata: inspects · Property viewers show parsed metadata objects.
- Tool Windows → Card Parsers: inspects · Card viewer presents parsed card details.
- Tool Windows → Shared UI: shares · Tool windows reuse shared logging and waiting controls.
- Dialogs → File Tools: operates on · Dialogs support path selection and filesystem-based actions.
- Modpack Tool → Mod Metadata: processes · Modpack tooling works over zipmod entries and manifests.
- Modpack Tool → File Tools: verifies · Tooling validates archive and configuration structures.
- Updater App → Update Sources: loads · Updater selects among remote source adapters.
- Updater App → Update Flow: models · Updater uses task and item models to describe work.
- Updater App → Download Coordinator: executes · Downloader coordinates transfer and status reporting.
- Download Coordinator → Update Sources: pulls from · Coordinator fetches data through source implementations.
- Download Coordinator → Update Flow: updates · Download state is reflected in update tasks and statuses.
- Update Sources → File Tools: applies to · Update sources eventually modify local files through installer flows.
- Mod Metadata → Ext Data: parses with · Mod loaders extract embedded metadata through extension parsers.
- Shared UI → Localization: localizes with · Shared controls and dialogs use translated resources.
- Main Window → Localization: localizes with · Main UI strings are resource-driven.
- File Tools → SB3UGS: integrates with · File and asset workflows can hand off to bundled tooling.
- Tests → Mod Metadata: checks · Tests validate sideloader version comparison behavior.
- Settings → Main Window: persists · Settings support desktop user preferences and state.