# timothyhay256/mikumikuloader architecture

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

- Interactive diagram: https://gitdiagram.com/timothyhay256/mikumikuloader
- Repository: https://github.com/timothyhay256/mikumikuloader

## Overview

##### Project type and purpose
- MikuMikuLoader is a network-based game-mod proxy and web UI platform for Project Sekai, written in Rust, with a Python helper for AssetBundle creation.
- It functions as a local DNS/HTTP proxy, a REST API server, and a static web UI, orchestrating binary AssetBundle injections and story conversions via UnityPy.

##### File structure
- Top-level:
- Cargo.toml / Cargo.lock / build.rs → Rust project, build configuration.
- `.github/workflows/rust.yml` → CI pipeline for build/test.
- `*.toml` files → runtime configuration (mods, injections, certs).
- `python/story_to_assetbundle.py` → Python helper script integrated during build or on-demand.
- `src/` (Rust backend):
- main.rs → entrypoint, HTTP/DNS server initialization.
- routes.rs → REST endpoints (mod management, status, cert gen).
- mods.rs, assetbundle.rs, scenario.rs → core injection logic (manage mod index, build/serve AssetBundles, scenario/story conversion).
- utils.rs → shared helpers.
- `static/` (Frontend/UI assets):
- HTML pages: mod-manager.html, server-status.html, certificate-gen.html, custom-story.html, index.html.
- JS/CSS subfolders: interactive UI, API calls to backend.
- Images, styling, client logic.
- `python/`:
- UnityPy integration to build `.unity3d` AssetBundles from JSON stories.
- Configuration TOMLs for injection pipelines and the main loader (`MikuMiku.toml`, `sekai-injector.toml`).

##### README for additional insights
- Purpose: purely network-based modding, no client modifications.
- Features: DNS server, certificate generation, auto resource download, cache invalidation, AssetBundle injection, story conversion.
- Dependencies: Rust toolchain, Python 3 + UnityPy library for final packaging.
- Roadmap indicates ongoing work on custom stories and deeper UI integration.

##### Main components and their relationships
a. Game Client
- Configured to use custom DNS/HTTPS proxy.
- Requests game assets & data.
b. DNS & HTTPS Proxy (Rust server)
- Resolves Sekai domains to local server IP.
- Presents CA certificate (self-signed via cert-gen module).
c. REST API Server (Rust backend)
- Exposes `/mods`, `/inject`, `/status`, `/cert` endpoints.
- Serves static UI and responds to AJAX calls.
d. AssetBundle Injection Engine (Rust + Python)
- Rust routes invoke Python script via child process (build.rs integration or runtime spawn).
- Python uses UnityPy to bundle JSON → `.unity3d`.
- Rust streams generated bundles back to the client/game.
e. Static Web UI
- HTML/JS pages for mod manager, story editor, cert gen, server status.
- Communicates with REST API.
f. Configuration Store
- TOML files define injection mappings, mod indexes, cert parameters.
g. External Dependencies
- UnityPy (Python library) for asset packaging.
- Project Sekai master DB (auto-downloaded assets).

Relationships:
- Browser UI ↔ REST API over HTTP.
- Game Client ↔ DNS/HTTPS Proxy (game traffic hijacked to inject mods).
- REST API ↔ Python script (for heavy build tasks).
- Rust backend ↔ file system (reads/writes bundles, configs).
- Rust backend ↔ external Sekai CDN (to auto-download resources).

##### Architectural patterns and design principles
- Separation of concerns: DNS proxy, HTTP API, and build logic modularized.
- Polyglot orchestration: Rust core with Python helper for specialized tasks.
- Configuration-driven injection pipelines (TOML).
- Static asset serving alongside dynamic endpoints (Full-stack single-binaries).
- Minimal statefulness: mostly stateless REST calls; file-based cache/injection.

##### Detail
- Rust module (`routes`, `mods`, `assetbundle`, `scenario`) as separate sub-components or group them in a “Injection Engine”.
- Python script as an external subprocess/service.
- TOML files as config entities feeding into both the Rust server and the Python builder.
- How the CI (`.github/workflows/rust.yml`) fits in for build/deploy, if relevant.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "External Systems"
        GameClient((Game Client)):::external
        CDN((Sekai CDN)):::external
        UnityPy((UnityPy)):::external
    end

    subgraph "Networking Layer"
        DNSProxy["DNS/HTTPS Proxy"]:::backend
    end

    subgraph "Application Layer"
        RESTAPI["REST API Server"]:::backend

        subgraph "Injection Engine"
            Mods["Mod Management Module"]:::backend
            AssetBundle["AssetBundle Injection Engine"]:::backend
            Scenario["Story Conversion/Scenario Injection"]:::backend
            Utils["Shared Helper Utilities"]:::backend
            PythonBuilder(("Python AssetBundle Builder")):::external
        end
    end

    subgraph "Data Layer"
        Configs[(TOML Config Store)]:::config
        Cache[(On-disk AssetBundle Cache)]:::config
    end

    subgraph "Static Web UI"
        subgraph "HTML Pages"
            ModUI["Mod Manager UI"]:::frontend
            StatusUI["Server Status UI"]:::frontend
            CertUI["Certificate Generation UI"]:::frontend
            StoryUI["Custom Story Editor UI"]:::frontend
            Index["Main Landing Page"]:::frontend
        end
        subgraph "JS Logic"
            JSMod["mod-manager.js"]:::frontend
            JSStatus["server-status.js"]:::frontend
            JSCert["certificate-gen.js"]:::frontend
            JSStory["custom-story.js"]:::frontend
        end
        Style["style.css"]:::config
        Images["Images"]:::config
    end

    %% Connections
    GameClient -->|"DNS query & HTTPS traffic"| DNSProxy
    DNSProxy -->|"Proxied Game Requests"| RESTAPI
    RESTAPI -->|"serves API & UI"| Index
    RESTAPI -->|"serves API & UI"| ModUI
    RESTAPI -->|"serves API & UI"| StatusUI
    RESTAPI -->|"serves API & UI"| CertUI
    RESTAPI -->|"serves API & UI"| StoryUI

    ModUI -->|"AJAX calls"| RESTAPI
    StatusUI -->|"AJAX calls"| RESTAPI
    CertUI -->|"AJAX calls"| RESTAPI
    StoryUI -->|"AJAX calls"| RESTAPI

    JSMod --> RESTAPI
    JSStatus --> RESTAPI
    JSCert --> RESTAPI
    JSStory --> RESTAPI

    RESTAPI -->|"uses modules"| Mods
    RESTAPI -->|"uses modules"| AssetBundle
    RESTAPI -->|"uses modules"| Scenario
    RESTAPI -->|"uses utilities"| Utils

    AssetBundle -->|"spawns subprocess"| PythonBuilder
    PythonBuilder -->|"bundles via UnityPy"| AssetBundle

    Mods --> Cache
    AssetBundle --> Cache
    Scenario --> Cache

    RESTAPI -->|"reads/writes"| Configs
    Mods --> Configs
    AssetBundle --> Configs
    Scenario --> Configs

    RESTAPI -->|"fetch assets"| CDN

    %% Click Events
    click DNSProxy "https://github.com/timothyhay256/mikumikuloader/blob/main/src/main.rs"
    click RESTAPI "https://github.com/timothyhay256/mikumikuloader/blob/main/src/routes.rs"
    click Mods "https://github.com/timothyhay256/mikumikuloader/blob/main/src/mods.rs"
    click AssetBundle "https://github.com/timothyhay256/mikumikuloader/blob/main/src/assetbundle.rs"
    click Scenario "https://github.com/timothyhay256/mikumikuloader/blob/main/src/scenario.rs"
    click Utils "https://github.com/timothyhay256/mikumikuloader/blob/main/src/utils.rs"
    click PythonBuilder "https://github.com/timothyhay256/mikumikuloader/blob/main/python/story_to_assetbundle.py"
    click ModUI "https://github.com/timothyhay256/mikumikuloader/blob/main/static/mod-manager.html"
    click StatusUI "https://github.com/timothyhay256/mikumikuloader/blob/main/static/server-status.html"
    click CertUI "https://github.com/timothyhay256/mikumikuloader/blob/main/static/certificate-gen.html"
    click StoryUI "https://github.com/timothyhay256/mikumikuloader/blob/main/static/custom-story.html"
    click Index "https://github.com/timothyhay256/mikumikuloader/blob/main/static/index.html"
    click JSMod "https://github.com/timothyhay256/mikumikuloader/blob/main/static/js/mod-manager.js"
    click JSStatus "https://github.com/timothyhay256/mikumikuloader/blob/main/static/js/server-status.js"
    click JSCert "https://github.com/timothyhay256/mikumikuloader/blob/main/static/js/certificate-gen.js"
    click JSStory "https://github.com/timothyhay256/mikumikuloader/blob/main/static/js/custom-story.js"
    click Style "https://github.com/timothyhay256/mikumikuloader/blob/main/static/css/style.css"
    click Images "https://github.com/timothyhay256/mikumikuloader/tree/main/static/images"

    %% Styles
    classDef backend fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef frontend fill:#fff3cd,stroke:#856404,color:#856404
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
