# mindstorm38/portablemc architecture

> Architecture diagram of the GitHub repository mindstorm38/portablemc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mindstorm38/portablemc
- Repository: https://github.com/mindstorm38/portablemc

## Overview

##### Project Type and Overall Purpose
- This is a Python-based command-line launcher (with its own API) that installs and starts Minecraft. It supports both official Minecraft and several popular mod loaders (Fabric, Forge, NeoForge, LegacyFabric, and Quilt), with capabilities for authentication (via Microsoft or Yggdrasil), downloading necessary game resources, and starting up a proper Java Virtual Machine.
- The application is set up as a CLI tool and a developer library (“portablemc”), making it both an end-user tool and an API for integrations.

##### Analyzing the File Structure
- The top-level directories:
- .github: Contains GitHub configurations (workflows and funding info) that manage CI/CD and project metadata.
- doc: Contains documentation (like API.md) with additional technical details.
- portablemc: The main package with modules such as __main__.py (for command-line entry), auth.py (handling authentication), cli/ (the command-line parser components), download.py (resource downloading), fabric.py, forge.py, http.py, standard.py, util.py and more. These files are split by responsibility.
- test: Contains test modules and sample data for unit testing various functionalities.
- pyproject.toml: Likely conveys the package build and dependency management configuration (possibly managed by Poetry).

##### Key Components to Highlight
a. User Interface/CLI Layer:
- The command-line entry point (portablemc/__main__.py) and the CLI subpackage (portablemc/cli/*) that parses user commands and flags. This layer is responsible for interpreting the user’s input (like starting Minecraft, authentication, and option flags such as JVM arguments).

b. Core Launcher Logic:
- Modules such as download.py, standard.py, and util.py that handle the core business logic (checking version manifests, initiating downloads, processing configuration data).
- Mod loader-specific modules (fabric.py, forge.py, etc.) that encapsulate the logic necessary to install and configure mod loaders.

c. Authentication and Session Management:
- The auth.py module which manages user logins, tokens, and session persistence (with reference in the README to portablemc_auth.json).
- Related subcommands in the CLI for login/logout and session handling.

d. Networking and External Service Interaction:
- The http.py module manages network operations such as downloading version manifests, assets, and connecting to Minecraft/Microsoft authentication endpoints.
- A clear link between the download/HTTP modules and external services (e.g. Mojang servers, mod loader distribution endpoints).

e. Java Virtual Machine (JVM) and Game Execution:
- Although the Java runtime isn’t implemented in Python, clearly denote how the launcher interfaces with an external JVM. Illustrate that after preparing all game resources and configurations, the core logic issues a call to launch the Minecraft Java process with proper memory and garbage-collection arguments.

f. Testing and Development:
- Separate components representing the test suite (test/ folder), emphasizing how unit tests verify individual modules like CLI parsing, installation routines, and version searching.

g. Configuration and Deployment:
- Files like pyproject.toml, .github workflows, and codecov.yml indicate CI/CD integration, code coverage reporting, and dependency management. These can be depicted as “support” or “infrastructure” components that ensure code quality and automated testing.

##### Architectural Patterns and Relationships
- A modular design that separates concerns:
- The CLI/front-end interacts with the Core Launcher components.
- Authentication, downloading, mod loader selection, and JVM launch are distinct functional units.
- For example, user input flows from the CLI into the authentication and download modules.
- Once resources and configurations are prepared, control is passed to the game launcher which communicates with the external JVM.
- Dependencies (for instance, the CLI module relies on submodules in portablemc/cli and further calls into util and network modules).

- Detail should not be minimal—aim to include as many components as possible by splitting the core functionality (i.e., show that mod loader support itself has multiple flows: one for Fabric, one for Forge, etc.)
- Use annotations to briefly explain the role of each component (e.g., “Auth Module: fetches and caches session tokens”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface / CLI Layer
    subgraph "User Interface / CLI Layer"
        CLIEntry["CLI Entry (portablemc/__main__.py)"]:::cli
        CLIParser["CLI Parser (portablemc/cli/)"]:::cli
    end

    %% Core Launcher Logic
    subgraph "Core Launcher Logic"
        DownloadManager["Download Manager (portablemc/download.py)"]:::core
        VersionManager["Version Manager (portablemc/standard.py)"]:::core
        UtilModules["Util Modules (portablemc/util.py)"]:::core
        FabricLoader["Fabric Loader (portablemc/fabric.py)"]:::core
        ForgeLoader["Forge Loader (portablemc/forge.py)"]:::core
    end

    %% Authentication and Session Management
    subgraph "Authentication"
        AuthModule["Auth Module (portablemc/auth.py)"]:::auth
    end

    %% Networking and External Service Interaction
    subgraph "Networking"
        NetworkManager["Network Manager (portablemc/http.py)"]:::network
    end

    %% External Services
    subgraph "External Services"
        ExtServices["Minecraft/Microsoft API & Mod Loader Repos"]:::external
    end

    %% JVM Launcher
    JVMManager["JVM Manager (External Java Process)"]:::jvm

    %% Support Components
    subgraph "Support & Infrastructure"
        TestSuite["Test Suite (test/)"]:::test
        ConfigCI["Configuration & CI/CD (pyproject.toml, .github/, codecov.yml)"]:::config
        Documentation["Documentation (doc/API.md)"]:::doc
    end

    %% Data Flow Connections
    CLIEntry -->|"initiates"| CLIParser
    CLIParser -->|"parses and routes"| AuthModule
    CLIParser -->|"parses and routes"| VersionManager
    CLIParser -->|"parses and routes"| DownloadManager
    CLIParser -->|"selects mod loader"| FabricLoader
    CLIParser -->|"selects mod loader"| ForgeLoader

    AuthModule -->|"auth requests"| NetworkManager
    VersionManager -->|"requests version info"| NetworkManager
    DownloadManager -->|"downloads resources"| NetworkManager
    DownloadManager -->|"uses"| UtilModules

    NetworkManager -->|"communicates with"| ExtServices
    AuthModule -->|"verifies identity"| ExtServices

    DownloadManager -->|"prepares game assets"| JVMManager
    VersionManager -->|"triggers game setup"| JVMManager

    %% Support connections (non-critical flows)
    TestSuite ---|"tests"| CLIParser
    TestSuite ---|"tests"| DownloadManager
    TestSuite ---|"tests"| VersionManager

    ConfigCI ---|"supports"| CLIEntry
    ConfigCI ---|"supports"| AuthModule
    ConfigCI ---|"supports"| DownloadManager

    Documentation ---|"guides"| CLIParser
    Documentation ---|"guides"| AuthModule

    %% Click Events
    click CLIEntry "https://github.com/mindstorm38/portablemc/blob/main/portablemc/__main__.py"
    click CLIParser "https://github.com/mindstorm38/portablemc/tree/main/portablemc/cli/"
    click DownloadManager "https://github.com/mindstorm38/portablemc/blob/main/portablemc/download.py"
    click VersionManager "https://github.com/mindstorm38/portablemc/blob/main/portablemc/standard.py"
    click UtilModules "https://github.com/mindstorm38/portablemc/blob/main/portablemc/util.py"
    click FabricLoader "https://github.com/mindstorm38/portablemc/blob/main/portablemc/fabric.py"
    click ForgeLoader "https://github.com/mindstorm38/portablemc/blob/main/portablemc/forge.py"
    click AuthModule "https://github.com/mindstorm38/portablemc/blob/main/portablemc/auth.py"
    click NetworkManager "https://github.com/mindstorm38/portablemc/blob/main/portablemc/http.py"
    click TestSuite "https://github.com/mindstorm38/portablemc/tree/main/test/"
    click ConfigCI "https://github.com/mindstorm38/portablemc/tree/main/.github/"
    click ConfigCI "https://github.com/mindstorm38/portablemc/blob/main/pyproject.toml"
    click ConfigCI "https://github.com/mindstorm38/portablemc/blob/main/codecov.yml"
    click Documentation "https://github.com/mindstorm38/portablemc/blob/main/doc/API.md"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef auth fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef network fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef external fill:#FF6347,stroke:#000,stroke-width:1px;
    classDef jvm fill:#F08080,stroke:#000,stroke-width:1px;
    classDef test fill:#FFC0CB,stroke:#000,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef doc fill:#D8BFD8,stroke:#000,stroke-width:1px;
```
