Skip to content

Architecture 00 Overview

Jump to bottom
Alex edited this page Oct 2, 2026 · 2 revisions

Aurelia: Architecture Wiki

A fast, lightweight, command-line Steam launcher and library manager written in Rust (edition 2024). Talks to Steam's real network protocols via steam-vent, and launches games natively or through Proton/Wine. No CEF, no WebView, no GUI.

This wiki is a per-subsystem architectural reference generated from a full read of the ~27 kLOC src/ tree (69 files) plus the integration test suite. It exists to support the umu-launcher integration, so every page carries a launch-relevant notes section.

Note

File and line references on these pages predate the source reorganisation. Code that used to live in src/main.rs and flat src/*.rs files now lives under src/commands/ (command handlers), src/core/ (config, models, utils, net, errors), and src/web/ (storefront, OpenID, web tokens, CM list). Line numbers like src/main.rs:2725 are therefore approximate. Behaviour that changed in v0.1.37–v0.1.38 has been patched into the affected pages. The modules added in that range are:

Module Role Since
src/core/error.rs ErrorKind, TypedError, classify(): typed errors, JSON type, exit codes 75/77 v0.1.37-2
src/core/locale.rs System-locale parsing → Steam language name and store country v0.1.37-2
src/core/net.rs (send_with_retry) Retrying HTTP: backoff on timeouts/502–504, typed 429 handling v0.1.37-2
src/core/session_crypto.rs OS-keyring-keyed encryption of session.json (replaces password encryption) v0.1.37
src/commands/store.rs price, search, deals, similar, players, events, news, reviews, wishlist, image --list v0.1.37-2 / v0.1.38
src/steam_client/storequery.rs StoreQuery searches (search, deals, similar) v0.1.38
src/steam_client/tags.rs, tags_table.rs, genres_table.rs, categories.rs Store tags, genres and categories over the CM (replaces SteamSpy) v0.1.37-2 / v0.1.38
src/steam_client/players.rs, events.rs Current player counts, active store events v0.1.38
src/steam_client/ident.rs, profile.rs, wishlist.rs User identifiers, CM profiles, wishlists (replace the Community XML lookup) v0.1.38
src/web/discovery.rs news and reviews from public web endpoints v0.1.38

Page index

# Page Subsystem Key files
00 this page Overview, layout, end-to-end launch flow
01 CLI & Entrypoint clap command tree, dispatch, main() main.rs, lib.rs
02 Config & Models LauncherConfig, GameConfig, GameRunner, data models config.rs, models.rs, store.rs
03 Steam Client Core connection, auth, session, host-Steam process steam_client.rs, steam_client/client.rs, process.rs
04 Content & Install 4-phase download pipeline, manifests, install/move steam_client/{content,install,manifests,manage}.rs
05 Steam Library & Launch owned library, play_game, launch-entry selection steam_client/{library,launch}.rs
06 Social friends, chat, web session steam_client/{chat,friends}.rs, web_session.rs
07 Workshop & Market Workshop, Community Market (read-only) steam_client/{workshop,workshop_manifest,market}.rs
08 Library & Local Library owned+installed merge, on-disk scan, CM list library.rs, local_library.rs, cm_list.rs
09 Launch Pipeline the 10-stage staged launch pipeline launch/pipeline.rs, launch/stages/*
10 Launch Validators & DLL invariants, override conflicts, DXVK/VKD3D resolution launch/validators/*, launch/dll_provider_resolver.rs
11 Proton & Runners runtime download/discovery, the Runner trait proton.rs, infra/runners/*
12 Cloud Sync & Relocate Steam Cloud sync, library-folder moves cloud_sync.rs, relocate.rs
13 Daemon shared-session daemon, IPC, background installs daemon/*
14 Logging Infra tracing, per-launch session logs, Wine log analysis infra/logging/*
15 Utils & Misc build_runner_command, prefix resolution, running/stop utils.rs, running.rs, proc_admin.rs, luxtorpeda.rs, …
16 Test Suite launch/Proton-focused integration tests tests/*
17 umu Runner the UmuRunner (umu-launcher Proton backend) infra/runners/umu.rs, launch/stages/resolve_components.rs

Module map

src/
├── main.rs ............... CLI command tree (clap) + per-command handlers  → [01]
├── lib.rs ............... crate module declarations
├── config.rs ........... LauncherConfig / GameConfig / GameRunner          → [02]
├── models.rs ........... domain types (games, depots, launch info)         → [02]
├── store.rs ............ storefront HTTP lookup (info --extended)          → [02]
├── steam_client.rs ..... SteamClient: one steam-vent Connection            → [03]
│   └── steam_client/
│       ├── client.rs ........ connect / login / session                    → [03]
│       ├── process.rs ....... host-Steam + game process control            → [03]
│       ├── content.rs ....... CDN content fetch
│       ├── install.rs ....... 4-phase install pipeline                     → [04]
│       ├── manifests.rs ..... PICS + depot + appmanifest.acf
│       ├── manage.rs ........ uninstall/move/relink/import, DLC
│       ├── library.rs ....... owned library (PICS)                         → [05]
│       ├── launch.rs ........ play_game: launch-entry selection + dispatch → [05]  ★
│       ├── chat.rs / friends.rs ..... social                               → [06]
│       └── workshop*.rs / market.rs . workshop + market                    → [07]
├── library.rs / local_library.rs / cm_list.rs ... library views            → [08]
├── launch/ ............. STAGED LAUNCH PIPELINE                             → [09]  ★★
│   ├── pipeline.rs ......... PipelineContext + orchestration
│   ├── stages/ ............. 10 ordered stages (resolve → build → spawn)
│   ├── validators/ ......... pre-launch invariants & override checks        → [10]
│   └── dll_provider_resolver.rs ... DXVK/VKD3D/NVAPI resolution             → [10]
├── proton.rs ........... Proton/Wine-GE download manager + discovery        → [11]  ★
├── infra/
│   ├── runners/ ........ Runner trait + WineTkgRunner + LuxtorpedaRunner    → [11]  ★★
│   └── logging/ ........ tracing + per-launch session logs                  → [14]
├── cloud_sync.rs / relocate.rs ........ Cloud + moves                       → [12]
├── daemon/ ............. shared-session daemon + IPC                        → [13]
├── utils.rs ............ build_runner_command, prefix resolution, helpers   → [15]  ★
├── running.rs / proc_admin.rs ......... running-game tracking & stop        → [15]
└── luxtorpeda.rs ....... native-engine plugin manager                      → [15]

★ = on the launch path  ★★ = primary umu integration surface

End-to-end launch flow (aurelia play <appid>)

This is the spine that the umu integration plugs into. Stars mark the points where umu substitutes for direct Proton invocation.

aurelia play <appid> [--proton X|--steam|--native-engine|--windows]
  │  main.rs::cmd_play  (main.rs:2725)
  │    • resolve runner: --proton → per-game forced_proton_version → global proton_version
  │    • pre-launch update check
  ▼
SteamClient::play_game            (steam_client/launch.rs:8)
  │    • get_product_info → parse_launch_info_from_vdf → pick installed launch entry
  │    • decide native_windows vs Proton   (launch.rs:82-94)
  │    • Cloud sync_down  (launch.rs:117)         ◀── pre-launch bracket
  │
  ├─ native_windows ─▶ spawn_windows_native        (no pipeline, no Proton)
  │
  └─ else ─▶ spawn_game_process   (steam_client/process.rs:345)
                │  builds PipelineContext, runs LaunchPipeline::with_default_stages()
                ▼
        ┌──────────────── STAGED LAUNCH PIPELINE (launch/pipeline.rs) ─────────────┐
        │ 1 ResolveGame        exe/cwd/install dir                                 │
        │ 2 ResolveProfile     merge LauncherConfig + GameConfig + UserAppConfig   │
        │ 3 ResolveComponents  pick Runner: Native / WineTkg / Luxtorpeda   ★ umu  │
        │ 4 ResolveDllProviders  DXVK/VKD3D/NVAPI choices                  ★ umu?  │
        │ 5 PreparePrefix      compatdata/pfx, symlink DLLs                ★ umu   │
        │ 6 BuildEnvironment   (delegates to runner.build_env)                     │
        │ 7 BuildCommand       runner.build_command → utils::build_runner_command  │
        │                       → "proton run <exe>" | "wine <exe>"         ★★ umu │
        │ 8 Preflight          last invariant checks                              │
        │ 9 SpawnProcess       spawn child, register in running.rs                 │
        │ 10 Finalize          summary.json, log scan                             │
        └──────────────────────────────────────────────────────────────────────────┘
                │  child.wait()  (blocks — runs inside the daemon process)
                ▼
        Cloud sync_up  (launch.rs:164)             ◀── post-launch bracket

Key facts that shape the integration (each detailed on its page):

  • Single command chokepoint. Every Proton/Wine command is emitted by utils::build_runner_command (utils.rs:6). It produces proton run <exe> or bare wine <exe> and nothing else. This is the one place the umu-run shape is added. See [15].
  • One trait, swappable runners. Runner (infra/runners/trait.rs:32) has name / prepare_prefix / build_env / build_command / launch. WineTkgRunner (Proton) and LuxtorpedaRunner (native) already prove the trait spans very different backends. A UmuRunner is the third impl. See [11].
  • Runner selection is one branch. ResolveComponentsStage (launch/stages/resolve_components.rs:79) maps a LaunchTarget to a runner. A GameRunner::Umu (config) flows here. See [09].
  • Config has a template. GameRunner::{Auto,Luxtorpeda} and the luxtorpeda_enabled/luxtorpeda_path pair are the exact precedent for GameRunner::Umu + umu_enabled/umu_path. See [02].
  • Prefix is resolved centrally. utils::steam_wineprefix_for_game (utils.rs:1225) yields <library>/steamapps/compatdata/<appid>/pfx. umu consumes this (WINEPREFIX = pfx, STEAM_COMPAT_DATA_PATH = its parent). See [15].
  • Process tracking keys on env, not PIDs. stop_game (steam_client/process.rs:120) sweeps /proc/*/environ for STEAM_COMPAT_APP_ID=<appid>, so the umu invocation must export STEAM_COMPAT_APP_ID or aurelia stop can't find re-parented children. See [15].
  • DLL ownership overlaps. Aurelia currently owns DXVK/VKD3D deployment and WINEDLLOVERRIDES (dll_provider_resolver.rs). umu (via protonfixes + the Proton runtime) does the same. The plan must pick one authoritative owner when umu is active. See [10].
  • Launch runs inside the daemon. play is forwarded to the shared-session daemon, so the umu/game process is parented to the long-lived daemon, not the CLI. See [13].
  • Output capture is file-based. The runner redirects child stderr to WINE_LOG_OUTPUT=<config_dir>/logs/wine_<appid>.log, which the pipeline scans for graphics evidence. umu's stderr must be wired into the same sink. See [14].

What umu brings (and why this integration is wanted)

umu-launcher (the Unified Launcher, formerly ULWGL) is the same tool Lutris, Heroic, and Bottles use to run Proton games outside Steam. It contributes two things Aurelia does not do today:

  1. The Steam Linux Runtime container (pressure-vessel / SteamLinuxRuntime_sniper): Aurelia currently launches Proton/Wine directly without the SLR container, so games relying on the container's bundled libraries can mis-behave (the README's Luxtorpeda note explicitly calls this out). umu sets the container up automatically.
  2. protonfixes: a community database of per-game launch fixes, keyed by GAMEID + STORE, applied automatically.

The trade-off (DLL/runtime ownership, an extra runtime dependency, container overhead) is covered in 17. The umu-launcher Runner.

Home

Users

Maintainers

Architecture

Clone this wiki locally