# brassworks-smp/brassworkslauncher architecture

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

- Interactive diagram: https://gitdiagram.com/brassworks-smp/brassworkslauncher
- Repository: https://github.com/brassworks-smp/brassworkslauncher

## Overview

#### Purpose and Entry Points
Brassworks Launcher is a cross-platform desktop Minecraft launcher for installing, managing, sharing, and launching custom modpack instances. The desktop binary is the Tauri shell at `frontend/src-tauri/src/main.rs`, initialized through `frontend/src-tauri/src/lib.rs`. React/Vite starts at `frontend/main.tsx` and renders the application root in `frontend/app/page.tsx`.

#### Desktop Boundary and Application State
Tauri is the trust boundary between the browser-rendered UI and local filesystem, process, network, and launcher operations. `frontend/src-tauri/src/commands.rs` exposes native commands; `frontend/src-tauri/src/state.rs` owns shared application state; `frontend/src-tauri/src/auth_window.rs` supports authentication flows. The frontend invokes this boundary through `frontend/lib/api.ts`, keeping views such as `frontend/components/PlayView.tsx` and `frontend/components/InstancesView.tsx` thin clients of Rust operations.

#### Core Launcher Domain
`crates/brassworks-core/src/lib.rs` is the principal native domain crate. Instance lifecycle—including creation, metadata, installation state, and instance-local paths—is centered in `crates/brassworks-core/src/instance.rs`, `crates/brassworks-core/src/paths.rs`, and `crates/brassworks-core/src/settings.rs`. Launch orchestration is in `crates/brassworks-core/src/launch.rs`; it combines resolved game assets, Java configuration, active instance files, and user settings into a Minecraft process launch.

#### Minecraft Resolution and Java Provisioning
The vendored `portablemc` crate resolves Minecraft and loader dependencies and supports downloading/launch preparation: `crates/portablemc/src/lib.rs`, `crates/portablemc/src/moj/mod.rs`, `crates/portablemc/src/fabric/mod.rs`, and `crates/portablemc/src/forge/mod.rs`. The separate Java crate, `crates/java/src/lib.rs`, provisions runtime requirements from Adoptium. This isolates upstream game/version/Maven/HTTP concerns from Brassworks-specific instance behavior.

#### Modpack Install, Sync, and Export
`crates/packwiz/src/installer.rs` implements packwiz installation, while `crates/packwiz/src/unsup/resolve.rs` implements resumable, hash-verified Unsup updates. `crates/brassworks-core/src/modpack.rs` coordinates these capabilities for launcher instances. Import/export and share workflows are represented by `crates/brassworks-core/src/import.rs`, `crates/brassworks-core/src/export.rs`, and `crates/brassworks-core/src/packwiz_share.rs`; pack format construction resides under `crates/packwiz/src/export/`. Content is sourced from Modrinth and CurseForge through `crates/packwiz/src/modrinth.rs` and `crates/packwiz/src/curseforge.rs`.

#### Publishing and Remote Integrations
Shared-pack publishing abstracts source-control hosts in `crates/brassworks-core/src/forge/mod.rs`, with implementations for GitHub and GitLab at `crates/brassworks-core/src/forge/github.rs` and `crates/brassworks-core/src/forge/gitlab.rs`. Credentials/account behavior is local to `crates/brassworks-core/src/auth.rs` and `crates/brassworks-core/src/account.rs`. External runtime services also include Modrinth, CurseForge, Mojang/Microsoft authentication, Adoptium, configured pack hosts, and the default schematic cache proxy.

#### Filesystem Content, Saves, and Schematics
Instance-associated user content is handled by dedicated core modules: global shared-file profiles/symlink repair in `crates/brassworks-core/src/global_files.rs`, worlds and backups in `crates/brassworks-core/src/saves.rs`, and schematic discovery/install/conversion in `crates/brassworks-core/src/schematics.rs` and `crates/brassworks-core/src/schematic_convert.rs`. Schematic remote access/cache behavior is separated into `crates/brassworks-core/src/createmod.rs` and `crates/brassworks-core/src/schematic_client_cache.rs`, with the cache base configurable by environment variable.

#### UI Workflow Layer and Distribution
The frontend organizes major launcher workflows into feature views—content, modpacks, servers, worlds, skins, settings, and command palette—under `frontend/components/` and command parsing/dispatch under `frontend/lib/cmd/`. Tauri platform configuration is in `frontend/src-tauri/tauri.conf.json` plus OS overrides. Releases produce native bundles; Linux repackaging targets AUR, Flatpak, and Snap via `packaging/aur/PKGBUILD`, `packaging/flatpak/com.brassworks.launcher.yaml`, and `packaging/snap/snapcraft.yaml`.

Main entry points: [`crates/brassworks-core/src/lib.rs`](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/lib.rs) (Brassworks core), [`crates/brassworks-core/src/launch.rs`](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/launch.rs) (Launch orchestration), [`frontend/src-tauri/src/commands.rs`](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/commands.rs) (Native commands), [`crates/brassworks-core/src/packwiz_share.rs`](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/packwiz_share.rs) (Import, export, sharing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_react["React/Vite entry<br/>frontend entry<br/>[main.tsx]"]
  node_ui["Launcher workflow UI<br/>React views<br/>[page.tsx]"]
  node_frontend_api["Native API client<br/>Tauri client<br/>[api.ts]"]
  node_tauri{{"Tauri shell<br/>desktop boundary<br/>[main.rs]"}}
  node_commands["Native commands<br/>Rust command API<br/>[commands.rs]"]
  node_app_state["Shared app state<br/>Rust state<br/>[state.rs]"]
end

subgraph group_core["Launcher core"]
  node_core_lib{{"Brassworks core<br/>domain crate<br/>[lib.rs]"}}
  node_instances["Instances and settings<br/>instance lifecycle<br/>[instance.rs]"]
  node_launch["Launch orchestration<br/>Minecraft launch<br/>[launch.rs]"]
  node_content["Saves and schematics<br/>instance content<br/>[saves.rs]"]
  node_sharing["Import, export, sharing<br/>pack workflows<br/>[packwiz_share.rs]"]
  node_auth["Accounts and credentials<br/>authentication<br/>[auth.rs]"]
end

subgraph group_runtime["Game runtime"]
  node_portablemc["portablemc resolver<br/>vendored game resolver<br/>[lib.rs]"]
  node_java["Java provisioning<br/>runtime crate<br/>[lib.rs]"]
  node_minecraft_process["Minecraft process<br/>local game process"]
end

subgraph group_modpacks["Modpack pipeline"]
  node_modpack["Modpack coordinator<br/>core integration<br/>[modpack.rs]"]
  node_packwiz["packwiz installer and export<br/>pack format crate<br/>[installer.rs]"]
end

subgraph group_external["External services"]
  node_minecraft(("Minecraft and loader services<br/>upstream services"))
  node_adoptium(("Adoptium<br/>Java runtime service"))
  node_catalogs(("Mod content catalogs<br/>Modrinth and CurseForge"))
  node_pack_hosts(("Pack hosts and Git forges<br/>remote publishing"))
end

node_react -->|"renders"| node_ui
node_ui -->|"invokes"| node_frontend_api
node_frontend_api -->|"crosses desktop boundary"| node_tauri
node_tauri -->|"registers"| node_commands
node_commands -->|"uses"| node_app_state
node_commands -->|"delegates to"| node_core_lib
node_core_lib -->|"manages"| node_instances
node_core_lib -->|"orchestrates"| node_launch
node_core_lib -->|"manages"| node_content
node_core_lib -->|"coordinates"| node_sharing
node_core_lib -->|"uses"| node_auth
node_launch -->|"reads active files and settings"| node_instances
node_launch -->|"resolves game assets"| node_portablemc
node_launch -->|"selects runtime"| node_java
node_launch -->|"starts"| node_minecraft_process
node_portablemc -->|"resolves and downloads"| node_minecraft
node_java -->|"provisions from"| node_adoptium
node_core_lib -->|"coordinates"| node_modpack
node_modpack -->|"installs and updates through"| node_packwiz
node_modpack -->|"updates instance content"| node_instances
node_packwiz -->|"sources mods from"| node_catalogs
node_sharing -->|"constructs pack formats with"| node_packwiz
node_sharing -->|"publishes and syncs"| node_pack_hosts
node_auth -->|"authenticates with"| node_minecraft

click node_react "https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/main.tsx"
click node_ui "https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/app/page.tsx"
click node_frontend_api "https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/lib/api.ts"
click node_tauri "https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/main.rs"
click node_commands "https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/commands.rs"
click node_app_state "https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/state.rs"
click node_core_lib "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/lib.rs"
click node_instances "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/instance.rs"
click node_launch "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/launch.rs"
click node_content "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/saves.rs"
click node_sharing "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/packwiz_share.rs"
click node_auth "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/auth.rs"
click node_portablemc "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/portablemc/src/lib.rs"
click node_java "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/java/src/lib.rs"
click node_modpack "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/modpack.rs"
click node_packwiz "https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/packwiz/src/installer.rs"

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_react,node_ui,node_frontend_api,node_tauri,node_commands,node_app_state toneBlue
class node_core_lib,node_instances,node_launch,node_content,node_sharing,node_auth toneAmber
class node_portablemc,node_java,node_minecraft_process toneMint
class node_modpack,node_packwiz toneRose
class node_minecraft,node_adoptium,node_catalogs,node_pack_hosts toneIndigo
```

## Components

### Desktop application

- [React/Vite entry](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/main.tsx): frontend entry · `frontend/main.tsx`
- [Launcher workflow UI](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/app/page.tsx): React views · Feature views and command dispatch for launcher workflows. · `frontend/app/page.tsx`
- [Native API client](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/lib/api.ts): Tauri client · `frontend/lib/api.ts`
- [Tauri shell](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/main.rs): desktop boundary · Trust boundary for browser UI and local native operations. · `frontend/src-tauri/src/main.rs`
- [Native commands](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/commands.rs): Rust command API · `frontend/src-tauri/src/commands.rs`
- [Shared app state](https://github.com/brassworks-smp/brassworkslauncher/blob/main/frontend/src-tauri/src/state.rs): Rust state · Also supports authentication windows. · `frontend/src-tauri/src/state.rs`

### Launcher core

- [Brassworks core](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/lib.rs): domain crate · `crates/brassworks-core/src/lib.rs`
- [Instances and settings](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/instance.rs): instance lifecycle · Owns instance metadata, paths, installation state, and settings. · `crates/brassworks-core/src/instance.rs`
- [Launch orchestration](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/launch.rs): Minecraft launch · `crates/brassworks-core/src/launch.rs`
- [Saves and schematics](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/saves.rs): instance content · Manages worlds, backups, shared files, and schematic workflows. · `crates/brassworks-core/src/saves.rs`
- [Import, export, sharing](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/packwiz_share.rs): pack workflows · Coordinates pack imports, exports, and shared-pack publishing. · `crates/brassworks-core/src/packwiz_share.rs`
- [Accounts and credentials](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/auth.rs): authentication · `crates/brassworks-core/src/auth.rs`

### Game runtime

- [portablemc resolver](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/portablemc/src/lib.rs): vendored game resolver · Resolves Minecraft, loaders, assets, and download preparation. · `crates/portablemc/src/lib.rs`
- [Java provisioning](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/java/src/lib.rs): runtime crate · `crates/java/src/lib.rs`
- **Minecraft process**: local game process

### Modpack pipeline

- [Modpack coordinator](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/brassworks-core/src/modpack.rs): core integration · Applies installation and update capabilities to launcher instances. · `crates/brassworks-core/src/modpack.rs`
- [packwiz installer and export](https://github.com/brassworks-smp/brassworkslauncher/blob/main/crates/packwiz/src/installer.rs): pack format crate · Installs packs, performs verified Unsup updates, and constructs exports. · `crates/packwiz/src/installer.rs`

### External services

- **Minecraft and loader services**: upstream services · Mojang versions/assets plus Fabric and Forge dependencies.
- **Adoptium**: Java runtime service
- **Mod content catalogs**: Modrinth and CurseForge
- **Pack hosts and Git forges**: remote publishing · Configured pack hosts plus GitHub and GitLab shared-pack repositories.

## Connections

- React/Vite entry → Launcher workflow UI: renders
- Launcher workflow UI → Native API client: invokes
- Native API client → Tauri shell: crosses desktop boundary
- Tauri shell → Native commands: registers
- Native commands → Shared app state: uses
- Native commands → Brassworks core: delegates to
- Brassworks core → Instances and settings: manages
- Brassworks core → Launch orchestration: orchestrates
- Brassworks core → Saves and schematics: manages
- Brassworks core → Import, export, sharing: coordinates
- Brassworks core → Accounts and credentials: uses
- Launch orchestration → Instances and settings: reads active files and settings
- Launch orchestration → portablemc resolver: resolves game assets
- Launch orchestration → Java provisioning: selects runtime
- Launch orchestration → Minecraft process: starts
- portablemc resolver → Minecraft and loader services: resolves and downloads
- Java provisioning → Adoptium: provisions from
- Brassworks core → Modpack coordinator: coordinates
- Modpack coordinator → packwiz installer and export: installs and updates through
- Modpack coordinator → Instances and settings: updates instance content
- packwiz installer and export → Mod content catalogs: sources mods from
- Import, export, sharing → packwiz installer and export: constructs pack formats with
- Import, export, sharing → Pack hosts and Git forges: publishes and syncs
- Accounts and credentials → Minecraft and loader services: authenticates with