# elouangrimm/opticlauncher architecture

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

- Interactive diagram: https://gitdiagram.com/elouangrimm/opticlauncher
- Repository: https://github.com/elouangrimm/opticlauncher

## Overview

1. **Product shape**
   - This is a **desktop Minecraft launcher** built primarily in **C++ with Qt**.
   - It is not just a GUI: it manages local game instances, downloads game/runtime assets, handles authentication, launches Minecraft, and manages modpacks/resources/worlds.
   - The README says this fork’s functional change is to **allow offline accounts** by removing the online-account restriction; the rest of the launcher architecture is inherited from Prism Launcher.

2. **Top-level application boundary**
   - The main executable lives under `launcher/` with `main.cpp`, `Application.*`, and `MainWindow.*`.
   - The app is a classic Qt desktop shell: windows, dialogs, pages, models, and background tasks all hang off the application object and its shared runtime context.
   - UI is separated from domain logic through Qt models, page providers, and task objects.

3. **Core domain: instances and profiles**
   - The launcher centers around **Minecraft instances**: `InstanceList`, `BaseInstance`, `MinecraftInstance`, and version/profile classes.
   - An instance is the unit of configuration, storage, and launch: it owns game version metadata, Java settings, mods/resources/worlds, logs, screenshots, and launch options.
   - This instance model is the main internal boundary between the UI and the underlying file/network operations.

4. **Task-based orchestration**
   - Most expensive work is modeled as **tasks** under `launcher/tasks/` and specialized subtrees.
   - There are generic task abstractions (`Task`, `SequentialTask`, `ConcurrentTask`) and many domain-specific tasks for creation, import, copy, migration, resource download, update checks, and launch steps.
   - This creates a clear pipeline boundary: UI triggers tasks, tasks do I/O and network work, and results are fed back into models/views.

5. **Minecraft launch pipeline**
   - Launch is assembled from step objects in `launcher/minecraft/launch/` and `launcher/launch/`.
   - The flow typically includes validating Java, preparing folders, reconstructing assets, extracting natives, checking libraries, applying mods/patches, and finally invoking the game process.
   - `LaunchController`, `LaunchTask`, `MinecraftTarget`, and related classes form the coordination layer between the instance config and the actual spawned Minecraft process.

6. **Java/runtime management**
   - Java is a first-class subsystem under `launcher/java/` and `launcher/ui/java/`.
   - It detects installed Javas, validates versions, downloads/installs archives when needed, and selects the runtime for each instance.
   - There is also a small Java helper/library area under `libraries/javacheck` and `libraries/launcher`, indicating the launcher uses both native C++ logic and JVM-side support code.

7. **Authentication and account handling**
   - Authentication code is isolated under `launcher/minecraft/auth/`.
   - It includes Microsoft/Xbox/Minecraft profile flows, skin fetching, entitlements, and session handling.
   - Because this fork’s README explicitly highlights **offline account unblocking**, account selection/login remains a distinct subsystem but with relaxed behavior around the online-account requirement.

8. **Network/download layer**
   - Network I/O is centralized in `launcher/net/`.
   - This layer provides downloads/uploads, request execution, metadata caching, checksum validation, and sinks for writing to files or memory.
   - Higher-level systems such as asset download, modpack import, skin upload, and update checking build on this layer rather than talking to the network directly.

9. **Minecraft content management**
   - The launcher has dedicated subsystems for **mods, resource packs, shader packs, texture packs, datapacks, and worlds** under `launcher/minecraft/mod/` and related folders.
   - It can scan local folders, parse metadata, inspect archives, export/import content, and present these as models in the UI.
   - This is a major architectural boundary: content management is separate from launch logic, even though both operate on the same instance directory.

10. **External modpack/provider integrations**
    - Provider-specific integrations live under `launcher/modplatform/`.
    - Supported ecosystems include **Modrinth, Curse/Flame, ATLauncher, FTB, Technic, Packwiz, and legacy FTB/import paths**.
    - These modules translate provider APIs/manifests into internal instance creation, update, export, and dependency-resolution tasks.

11. **UI composition**
    - The UI is heavily segmented into `launcher/ui/` pages, dialogs, widgets, setup wizard pages, and themed components.
    - Pages are organized by scope: **global settings**, **instance-specific pages**, and **modpack/provider pages**.
    - The UI mostly consumes model classes and emits user actions to tasks/controllers; it does not own the core business logic.

12. **Logging, news, screenshots, and tooling**
    - Supporting subsystems include launch log parsing/anonymization, news checking, screenshot upload, external tools/profilers, and updater integration.
    - These are auxiliary but architecturally important because they connect the launcher to user-facing services and external programs while keeping the main launch pipeline separate.

13. **Packaging and platform boundaries**
    - The repo is built around **CMake**, with **vcpkg**, **Nix/Flakes**, GitHub Actions workflows, and platform-specific packaging files.
    - There are explicit platform branches for **Windows, macOS, Linux**, plus sandboxing/security helpers and app metadata under `program_info/`.
    - This suggests a cross-platform desktop app with substantial OS-specific integration at the edges, but a shared core in the center.

14. **Validation and regression coverage**
    - `tests/` contains focused tests for parsing, filesystem behavior, version handling, packs, logs, tasks, and world/resource parsing.
    - The test data mirrors the domain model: packs, archives, manifests, logs, and world saves.
    - Architecturally, this indicates the repo’s critical contracts are parsing and content interpretation rather than backend APIs or web endpoints.

Main entry points: [`launcher/launch/LaunchStep.h`](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/launch/LaunchStep.h) (Launch steps), [`launcher/minecraft/MinecraftInstance.h`](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/MinecraftInstance.h) (Minecraft instance), [`launcher/minecraft/mod/Mod.h`](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/mod/Mod.h) (Content managers), [`launcher/net/NetJob.h`](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/net/NetJob.h) (Network layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop App"]
  node_main["App entry<br/>qt executable<br/>[main.cpp]"]
  node_application["Application<br/>qt runtime<br/>[Application.h]"]
  node_mainwindow["Main window<br/>ui shell<br/>[MainWindow.h]"]
  node_pages["Pages & dialogs<br/>ui composition"]
end

subgraph group_core["Core Domain"]
  node_instance_model[("Instances<br/>domain model<br/>[InstanceList.h]")]
  node_version_model["Versions<br/>version model<br/>[Version.h]"]
  node_settings["Settings<br/>config model<br/>[SettingsObject.h]"]
  node_fs_utils["FS helpers<br/>filesystem utils<br/>[FileSystem.h]"]
end

subgraph group_pipeline["Task Pipelines"]
  node_task_core(("Task core<br/>async framework<br/>[Task.h]"))
  node_instance_tasks["Instance tasks<br/>instance pipeline"]
  node_launch_pipeline["Launch pipeline<br/>launch orchestration<br/>[LaunchController.h]"]
  node_launch_steps["Launch steps<br/>step pipeline<br/>[LaunchStep.h]"]
end

subgraph group_content["Minecraft Content"]
  node_minecraft_instance[("Minecraft instance<br/>game instance")]
  node_java_runtime["Java runtime<br/>runtime subsystem<br/>[JavaChecker.h]"]
  node_auth["Accounts<br/>auth subsystem<br/>[AuthFlow.h]"]
  node_content_mgmt["Content managers<br/>content subsystem<br/>[Mod.h]"]
end

subgraph group_integrations["External Integrations"]
  node_providers["Mod platforms<br/>integration layer<br/>[ModIndex.h]"]
  node_net["Network layer<br/>http/download core<br/>[NetJob.h]"]
  node_aux_services["Aux services<br/>support subsystem<br/>[NewsChecker.h]"]
end

subgraph group_platform["Platform & Build"]
  node_platform_build["Build & packaging<br/>cross-platform build<br/>[CMakeLists.txt]"]
  node_tests["Tests<br/>regression suite<br/>[CMakeLists.txt]"]
end

node_main -->|"starts"| node_application
node_application -->|"hosts"| node_mainwindow
node_mainwindow -->|"navigates"| node_pages
node_pages -->|"reads/writes"| node_instance_model
node_pages -->|"binds"| node_settings
node_instance_model -->|"specializes"| node_minecraft_instance
node_minecraft_instance -->|"resolves"| node_version_model
node_minecraft_instance -->|"owns"| node_content_mgmt
node_task_core -->|"powers"| node_instance_tasks
node_task_core -->|"powers"| node_launch_pipeline
node_instance_tasks -->|"uses"| node_fs_utils
node_launch_pipeline -->|"assembles"| node_launch_steps
node_launch_steps -->|"checks"| node_java_runtime
node_launch_steps -->|"prepares"| node_minecraft_instance
node_java_runtime -->|"downloads"| node_net
node_auth -->|"requests"| node_net
node_content_mgmt -->|"syncs"| node_net
node_providers -->|"creates"| node_instance_tasks
node_providers -->|"maps"| node_content_mgmt
node_aux_services -->|"uses"| node_net
node_tests -->|"covers"| node_content_mgmt
node_tests -->|"covers"| node_launch_steps
node_platform_build -->|"packages"| node_application

click node_main "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/main.cpp"
click node_application "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/Application.h"
click node_mainwindow "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/ui/MainWindow.h"
click node_pages "https://github.com/elouangrimm/opticlauncher/tree/develop/launcher/ui/pages"
click node_instance_model "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/InstanceList.h"
click node_version_model "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/meta/Version.h"
click node_settings "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/settings/SettingsObject.h"
click node_fs_utils "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/FileSystem.h"
click node_task_core "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/tasks/Task.h"
click node_instance_tasks "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/InstanceCreationTask.h"
click node_launch_pipeline "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/LaunchController.h"
click node_launch_steps "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/launch/LaunchStep.h"
click node_minecraft_instance "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/MinecraftInstance.h"
click node_java_runtime "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/java/JavaChecker.h"
click node_auth "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/auth/AuthFlow.h"
click node_content_mgmt "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/mod/Mod.h"
click node_providers "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/modplatform/ModIndex.h"
click node_net "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/net/NetJob.h"
click node_aux_services "https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/news/NewsChecker.h"
click node_platform_build "https://github.com/elouangrimm/opticlauncher/blob/develop/CMakeLists.txt"
click node_tests "https://github.com/elouangrimm/opticlauncher/blob/develop/tests/CMakeLists.txt"

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_main,node_application,node_mainwindow,node_pages toneBlue
class node_instance_model,node_version_model,node_settings,node_fs_utils toneAmber
class node_task_core,node_instance_tasks,node_launch_pipeline,node_launch_steps toneMint
class node_minecraft_instance,node_java_runtime,node_auth,node_content_mgmt toneRose
class node_providers,node_net,node_aux_services toneIndigo
class node_platform_build,node_tests toneTeal
```

## Components

### Desktop App

Qt application shell, windows, pages, dialogs, and shared runtime context.

- [App entry](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/main.cpp): qt executable · Main application bootstrap and startup flow. · `launcher/main.cpp`
- [Application](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/Application.h): qt runtime · Top-level application object and shared state container. · `launcher/Application.h`
- [Main window](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/ui/MainWindow.h): ui shell · Primary desktop shell for instance management and navigation. · `launcher/ui/MainWindow.h`
- [Pages & dialogs](https://github.com/elouangrimm/opticlauncher/tree/develop/launcher/ui/pages): ui composition · Global settings, instance pages, setup wizard, and modal dialogs. · `launcher/ui/pages`

### Core Domain

Instances, versions, settings, filesystem helpers, and shared launcher state.

- [Instances](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/InstanceList.h): domain model · Instance list and instance base classes defining the main user-level unit. · `launcher/InstanceList.h`
- [Versions](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/meta/Version.h): version model · Version, metadata, and profile structures used to resolve game state. · `launcher/meta/Version.h`
- [Settings](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/settings/SettingsObject.h): config model · Persistent settings objects and per-instance overrides. · `launcher/settings/SettingsObject.h`
- [FS helpers](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/FileSystem.h): filesystem utils · Local filesystem, zip, JSON, time, and utility helpers. · `launcher/FileSystem.h`

### Task Pipelines

Long-running orchestration for creation, import, download, update, and launch.

- [Task core](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/tasks/Task.h): async framework · Generic task abstractions for sequential and concurrent orchestration. · `launcher/tasks/Task.h`
- [Instance tasks](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/InstanceCreationTask.h): instance pipeline · Creation, import, copy, migration, and resource update tasks. · `launcher/InstanceCreationTask.h`
- [Launch pipeline](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/LaunchController.h): launch orchestration · Launch controller and launch task assembly into game process start. · `launcher/LaunchController.h`
- [Launch steps](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/launch/LaunchStep.h): step pipeline · Preparatory steps such as Java checks, assets, natives, folders, and commands. · `launcher/launch/LaunchStep.h`

### Minecraft Content

Instance content, launch preparation, auth, Java, mods, worlds, and skins.

- [Minecraft instance](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/MinecraftInstance.h): game instance · Instance-specific game state, profiles, components, and load/check logic. · `launcher/minecraft/MinecraftInstance.h`
- [Java runtime](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/java/JavaChecker.h): runtime subsystem · Java detection, validation, metadata, and optional install/download flow. · `launcher/java/JavaChecker.h`
- [Accounts](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/auth/AuthFlow.h): auth subsystem · Microsoft/Xbox/Minecraft profile flows, sessions, and offline account handling. · `launcher/minecraft/auth/AuthFlow.h`
- [Content managers](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/minecraft/mod/Mod.h): content subsystem · Mods, resource packs, shader packs, datapacks, texture packs, and worlds. · `launcher/minecraft/mod/Mod.h`

### External Integrations

Provider APIs, network layer, updater, tools, and auxiliary services.

- [Mod platforms](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/modplatform/ModIndex.h): integration layer · Provider-specific pack APIs and import/export/update adapters. · `launcher/modplatform/ModIndex.h`
- [Network layer](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/net/NetJob.h): http/download core · Requests, downloads, uploads, sinks, caches, validation, and network jobs. · `launcher/net/NetJob.h`
- [Aux services](https://github.com/elouangrimm/opticlauncher/blob/develop/launcher/news/NewsChecker.h): support subsystem · News, logs, screenshots, external tools, profilers, and updater integration. · `launcher/news/NewsChecker.h`

### Platform & Build

Cross-platform packaging, native helpers, and build/test infrastructure.

- [Build & packaging](https://github.com/elouangrimm/opticlauncher/blob/develop/CMakeLists.txt): cross-platform build · CMake, vcpkg, Nix, GitHub Actions, app metadata, and platform packaging. · `CMakeLists.txt`
- [Tests](https://github.com/elouangrimm/opticlauncher/blob/develop/tests/CMakeLists.txt): regression suite · Focused parsing, filesystem, version, pack, log, task, and world tests. · `tests/CMakeLists.txt`

## Connections

- App entry → Application: starts · Program entry initializes the Qt application object.
- Application → Main window: hosts · Application owns the primary desktop shell.
- Main window → Pages & dialogs: navigates · Window composes and switches between global and instance pages.
- Pages & dialogs → Instances: reads/writes · UI edits and displays instance state through models.
- Pages & dialogs → Settings: binds · Pages present global and per-instance settings.
- Instances → Minecraft instance: specializes · Concrete Minecraft instances extend the core instance model.
- Minecraft instance → Versions: resolves · Instance state is anchored in version/profile metadata.
- Minecraft instance → Content managers: owns · Instances own mods, packs, worlds, screenshots, and related content.
- Task core → Instance tasks: powers · Specialized instance operations are built on generic task abstractions.
- Task core → Launch pipeline: powers · Launch orchestration is executed as tasks.
- Instance tasks → FS helpers: uses · Creation, import, and copy tasks manipulate local storage.
- Launch pipeline → Launch steps: assembles · The controller sequences launch preparation steps.
- Launch steps → Java runtime: checks · Launch preparation validates and selects Java.
- Launch steps → Minecraft instance: prepares · Launch steps derive process inputs from instance configuration.
- Java runtime → Network layer: downloads · Runtime installation and manifests are fetched over the network.
- Accounts → Network layer: requests · Authentication and profile flows depend on HTTP calls.
- Content managers → Network layer: syncs · Pack metadata, downloads, uploads, and updates go through the network layer.
- Mod platforms → Instance tasks: creates · Provider integrations drive install/import/update tasks.
- Mod platforms → Content managers: maps · Provider manifests are translated into internal content objects.
- Aux services → Network layer: uses · News, screenshots, uploads, and updater checks use shared network primitives.
- Tests → Content managers: covers · Tests validate parsing and content interpretation contracts.
- Tests → Launch steps: covers · Tests exercise launch-related parsing and behavior.
- Build & packaging → Application: packages · Build and packaging infrastructure produces the desktop application.
