illusionmods/kkmanager

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.