# freeproject089/bettermodsmanager architecture

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

- Interactive diagram: https://gitdiagram.com/freeproject089/bettermodsmanager
- Repository: https://github.com/freeproject089/bettermodsmanager

## Overview

1. **Top-level shape**
   Better Mod Manager is a desktop application built as a **Tauri shell**: a JavaScript/HTML/CSS frontend runs in a webview, while the Rust backend performs all privileged local work. The core boundary is UI vs. file-system/game-management logic.

2. **Frontend presentation layer**
   The `frontend/` tree is a modular ES2022 app with `app.js` as the main bootstrap, plus feature modules such as `mods.js`, `profiles.js`, `repo.js`, `onboarding.js`, `debug.js`, `benchmark.js`, and `interactive-docs.js`. Styling is plain CSS, and the UI includes embedded assets, localized strings, and diagram-based help content.

3. **Frontend state and API boundary**
   `state.js`, `api.js`, `utils.js`, and `components.js` form the client-side application layer. The frontend is not doing direct file or OS work; it calls into the Rust side through the Tauri command bridge and renders responses, errors, and diagnostics.

4. **Rust backend command layer**
   `src-tauri/src/commands/` is the main backend API surface. Commands are grouped by concern: mods, mod lists, profiles, tags, history, repository/repo-server, update/autoupdate, disk/image utilities, security, crash/debug, Discord integration, window control, and admin tooling such as ban and whitelist management. This is the executable core behind every privileged action.

5. **Domain model and application state**
   The backend models are organized around `profile`, `mod_entry`, `modlist`, `repo`, `tag`, and `history`. `src-tauri/src/state.rs` and `frontend/js/state.js` indicate a stateful app that keeps the current profile/game context, selected mods, and operational status in sync across the UI and backend.

6. **File-system and mod activation flow**
   The application’s main job is local mod management, so the critical runtime flow is: user action in the frontend → backend command → filesystem operation in the target game directory. The README’s “Smart Physical Copy” approach means files are copied and restored rather than managed by symlinks, with backup/restoration behavior and conflict detection around active mods.

7. **Import/export, sharing, and repository support**
   Mod sharing is a first-class subsystem: `.MM` lists, import/export, download links, local mod pooling, and repository handling all live around the `mods`, `modlist`, and `repo` command/model sets. This is also where the app can categorize external links such as GitHub, Drive, MEGA, or direct archives.

8. **Server/admin and multi-profile operations**
   The repository includes a dedicated server-management slice (`repo_server`, `ban_manager`, `whitelist_manager`, `omm`, `ovgme`) and a mini-server template under `src-tauri/src/templates/mini-server/`. That suggests the app can manage or assist with hosted/mod-sharing workflows, not just local installs. Profiles are a major partitioning boundary: each game/profile has its own paths, settings, and mod state.

9. **Diagnostics, update, and safety tooling**
   There are explicit backend commands for crash reporting, benchmarking, disk checks, image handling, and update checking. The README calls out GitHub-based update checks, and the Rust backend dependencies imply network and archive handling. Global locking and stateful backend commands point to serialized access around mutable local resources.

10. **Internationalization and documentation tooling**
   Localization is built into the frontend with `frontend/Lang/en.json`, `fr.json`, and `template.json`, plus `compare_i18n.py` and `tests/i18n_parity.test.py` to keep translations aligned. The `Update/` directory and `frontend/js/diagrams/` folder are documentation assets, not runtime subsystems, but they help explain the architecture and user-facing workflows.

11. **Packaging and runtime context**
   `src-tauri/tauri.conf.json`, Rust build files, and `package-lock.json` show a standard Tauri packaging pipeline: frontend assets are bundled into a native desktop executable. The app is therefore best diagrammed as a **local desktop orchestrator** with a thin UI layer and a Rust system layer that owns storage, updates, mod operations, and external integration.

Main entry points: [`frontend/js/api.js`](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/api.js) (Tauri API), [`frontend/js/app.js`](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/app.js) (App bootstrap), [`src-tauri/src/models/mod.rs`](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/models/mod.rs) (Domain models), [`src-tauri/src/commands/mods.rs`](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/mods.rs) (Mods commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_boot["App bootstrap<br/>frontend entry<br/>[app.js]"]
  node_ui_state["UI state<br/>client state<br/>[state.js]"]
  node_ui_api["Tauri API<br/>bridge<br/>[api.js]"]
  node_ui_features["Feature modules<br/>ui modules"]
  node_ui_components["Components<br/>ui helpers<br/>[components.js]"]
  node_ui_i18n["Localization<br/>translations<br/>[en.json]"]
  node_ui_docs["Interactive docs<br/>help/docs"]
end

subgraph group_backend["Rust backend"]
  node_cmd_mods["Mods commands<br/>backend api<br/>[mods.rs]"]
  node_cmd_modlist["Modlist commands<br/>backend api<br/>[modlist.rs]"]
  node_cmd_profile["Profile commands<br/>backend api<br/>[profile.rs]"]
  node_cmd_repo["Repo commands<br/>backend api<br/>[repo.rs]"]
  node_cmd_repo_server["Server commands<br/>backend api<br/>[repo_server.rs]"]
  node_cmd_ops["Ops commands<br/>backend api<br/>[update.rs]"]
  node_backend_state[("Backend state<br/>app state<br/>[state.rs]")]
  node_backend_models["Domain models<br/>[mod.rs]"]
  node_fs_utils["FS utils<br/>filesystem<br/>[fs_utils.rs]"]
  node_mini_server["Mini-server template"]
end

subgraph group_docs["Docs & assets"]
  node_docs_update["Update docs"]
end

node_ui_boot -->|"initializes"| node_ui_state
node_ui_boot -->|"loads"| node_ui_features
node_ui_boot -->|"renders with"| node_ui_components
node_ui_features -->|"calls"| node_ui_api
node_ui_state -->|"reads/writes"| node_ui_api
node_ui_i18n -.->|"localizes"| node_ui_boot
node_ui_docs -.->|"explains"| node_ui_features
node_ui_api -->|"invokes"| node_cmd_mods
node_ui_api -->|"invokes"| node_cmd_modlist
node_ui_api -->|"invokes"| node_cmd_profile
node_ui_api -->|"invokes"| node_cmd_repo
node_ui_api -->|"invokes"| node_cmd_repo_server
node_ui_api -->|"invokes"| node_cmd_ops
node_cmd_mods -->|"uses"| node_backend_state
node_cmd_modlist -->|"serializes"| node_backend_models
node_cmd_profile -->|"uses"| node_backend_models
node_cmd_repo -->|"uses"| node_backend_models
node_cmd_mods -->|"touches"| node_fs_utils
node_cmd_profile -->|"touches"| node_fs_utils
node_cmd_repo_server -->|"templates"| node_mini_server
node_cmd_ops -->|"uses"| node_backend_state
node_backend_models -.->|"feeds"| node_backend_state
node_docs_update -.->|"supports"| node_ui_docs

click node_ui_boot "https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/app.js"
click node_ui_state "https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/state.js"
click node_ui_api "https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/api.js"
click node_ui_components "https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/components.js"
click node_ui_i18n "https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/Lang/en.json"
click node_ui_docs "https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/interactive-docs.js"
click node_cmd_mods "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/mods.rs"
click node_cmd_modlist "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/modlist.rs"
click node_cmd_profile "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/profile.rs"
click node_cmd_repo "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/repo.rs"
click node_cmd_repo_server "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/repo_server.rs"
click node_cmd_ops "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/update.rs"
click node_backend_state "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/state.rs"
click node_backend_models "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/models/mod.rs"
click node_fs_utils "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/fs_utils.rs"
click node_mini_server "https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/templates/mini-server/server.hybrid.bat.template"
click node_docs_update "https://github.com/freeproject089/bettermodsmanager/blob/main/Update/changelog_since_7e839e.md"

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_ui_boot,node_ui_state,node_ui_api,node_ui_features,node_ui_components,node_ui_i18n,node_ui_docs toneBlue
class node_cmd_mods,node_cmd_modlist,node_cmd_profile,node_cmd_repo,node_cmd_repo_server,node_cmd_ops,node_backend_state,node_backend_models,node_fs_utils,node_mini_server toneAmber
class node_docs_update toneMint
```

## Components

### Frontend

Tauri webview UI and client-side app modules

- [App bootstrap](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/app.js): frontend entry · Main browser-side startup and feature wiring · `frontend/js/app.js`
- [UI state](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/state.js): client state · Shared frontend state and view synchronization · `frontend/js/state.js`
- [Tauri API](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/api.js): bridge · Frontend command boundary into Rust backend · `frontend/js/api.js`
- **Feature modules**: ui modules · Mods, profiles, repo, onboarding, debug, benchmarking, docs
- [Components](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/components.js): ui helpers · Reusable frontend rendering and interaction pieces · `frontend/js/components.js`
- [Localization](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/Lang/en.json): translations · Frontend language loading and translated strings · `frontend/Lang/en.json`
- [Interactive docs](https://github.com/freeproject089/bettermodsmanager/blob/main/frontend/js/interactive-docs.js): help/docs · Embedded diagrams and guided help content · `frontend/js/interactive-docs.js`

### Rust backend

Privileged local logic, commands, models, and filesystem coordination

- [Mods commands](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/mods.rs): backend api · Mod import, activation, copy, and conflict workflows · `src-tauri/src/commands/mods.rs`
- [Modlist commands](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/modlist.rs): backend api · .MM list management and import/export · `src-tauri/src/commands/modlist.rs`
- [Profile commands](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/profile.rs): backend api · Game/profile partitions, paths, and settings · `src-tauri/src/commands/profile.rs`
- [Repo commands](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/repo.rs): backend api · Repository links, downloads, and local mod sharing · `src-tauri/src/commands/repo.rs`
- [Server commands](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/repo_server.rs): backend api · Hosted/shared mod server management · `src-tauri/src/commands/repo_server.rs`
- [Ops commands](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/commands/update.rs): backend api · Update, disk, image, debug, crash, security, and window actions · `src-tauri/src/commands/update.rs`
- [Backend state](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/state.rs): app state · Serialized runtime state shared across commands · `src-tauri/src/state.rs`
- [Domain models](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/models/mod.rs): domain model · Profiles, mod entries, modlists, repo data, tags, and history · `src-tauri/src/models/mod.rs`
- [FS utils](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/fs_utils.rs): filesystem · File-system helpers for game directory operations · `src-tauri/src/fs_utils.rs`
- [Mini-server template](https://github.com/freeproject089/bettermodsmanager/blob/main/src-tauri/src/templates/mini-server/server.hybrid.bat.template): template · Generated server-side helper template · `src-tauri/src/templates/mini-server/server.hybrid.bat.template`

### Docs & assets

Localization, diagrams, and update documentation

- [Update docs](https://github.com/freeproject089/bettermodsmanager/blob/main/Update/changelog_since_7e839e.md): docs · Release notes and architectural writeups · `Update/changelog_since_7e839e.md`

## Connections

- App bootstrap → UI state: initializes · Bootstraps application state and UI flows
- App bootstrap → Feature modules: loads · Brings feature modules into the app
- App bootstrap → Components: renders with · Uses shared components during view composition
- Feature modules → Tauri API: calls · Features invoke backend actions through the bridge
- UI state → Tauri API: reads/writes · State is synchronized with backend responses and events
- Localization → App bootstrap: localizes · Language strings feed the UI bootstrap and modules
- Interactive docs → Feature modules: explains · Interactive help documents major workflows
- Tauri API → Mods commands: invokes · Frontend mod actions map to privileged backend commands
- Tauri API → Modlist commands: invokes · Frontend list import/export and sharing flows
- Tauri API → Profile commands: invokes · Frontend profile management maps to backend operations
- Tauri API → Repo commands: invokes · Frontend repository and download flows map here
- Tauri API → Server commands: invokes · Frontend server/admin workflows map here
- Tauri API → Ops commands: invokes · Frontend diagnostics, updates, and utility actions map here
- Mods commands → Backend state: uses · Mod operations rely on shared runtime state
- Modlist commands → Domain models: serializes · Lists are represented through the domain model layer
- Profile commands → Domain models: uses · Profiles and related context come from models
- Repo commands → Domain models: uses · Repository metadata and sharing data are modeled here
- Mods commands → FS utils: touches · Core mod flow performs file-system work in game directories
- Profile commands → FS utils: touches · Profile operations resolve and manage local paths
- Server commands → Mini-server template: templates · Server management can generate or use the mini-server template
- Ops commands → Backend state: uses · Diagnostic and control commands coordinate through shared state
- Domain models → Backend state: feeds · Model data is tracked in the runtime state
- Update docs → Interactive docs: supports · Documentation assets back the interactive help system
