Minecraft Intelligent Manager
MIM.
Modular systems engineering platform · Desktop + Cloud
Modpack architecture, deterministic crash diagnosis, static JVM bytecode analysis, and NBT binary recovery — seven decoupled engines on a typed event bus, spanning an Electron desktop app and MIM Hub (PWA) on Vercel.
Project philosophy
“Building a spaceship to go buy bread is ridiculous if your goal was just the bread. But if your goal was to learn how to build a spaceship, the true value lies in everything you had to break, learn, and connect to make that spaceship fly.”
My role & scope
Sole active developer: ~85k LOC, 8 ADRs, architecture boundaries in CI, and headless test suites. I own Desktop (Electron 42) and Hub (Next.js 16), the domain engines, MIM-Bot’s multi-provider gateway (Gemini / OpenRouter), and real PostgreSQL RLS policies.
Status
Active beta · v11.4.8
The Engineering Challenge
Someone installing modpacks by hand hits four concrete problems: the same JAR arrives from Modrinth and CurseForge under different names; Minecraft never says which mod crashed, only a raw JVM stacktrace; player `.dat` files corrupt; and Forge / Fabric / NeoForge / Quilt do not share compatibility rules. MIM attacks each with a dedicated engine — not a generic chatbot.
That is why there are seven domain engines that communicate only through typed events. Server Manager (SFTP, remote logs, RCON) is in progress on Desktop `/servers`: useful for diagnosis, not yet a complete hosting product.
Decoupled Domain Engines
Seven independent subsystems, each with a deterministic contract and a typed bus:
✦MIM Core — Runtime Abstraction
FS · Logger · SettingsShared filesystem, typed logger, and settings layer. Domain engines never import UI: Core and the typed event bus (`MimEventMap`) are the common contract. Import boundaries are enforced in CI with an AST linter.
✦Modpack Engine — Manifests & Build
Resolvers · Licenses · LoadersBuilds modpacks (AllUser / AllHost ZIP), resolves dependencies across Forge, Fabric, NeoForge, and Quilt, and audits licenses (ARR vs MIT/LGPL, including `quilt.mod.json`). Targets real loader incompatibilities and silently disabled assets.
✦SAGE — Crash Intelligence
Deterministic Diagnostics + AI ExplanationDeterministic pipeline: parses crash.log, classifies 8 failure categories (Mixin, version conflict, OOM…), correlates frames to mods, and scores evidence. The LLM (`SageExplainer` / MIM-Bot) only translates an already-verified JSON report. AI explains evidence; it does not invent it.
✦Aduana — Content-Addressed Storage
I/O & CAS ArchitectureCryptographic identity SHA-512 ≻ SHA-1. The same JAR served by Modrinth and CurseForge under different names is deduplicated; matching names with different hashes never collapse. Cache keyed on mtime + size: 8.0×–8.5× speedup from 1k to 25k files.
✦FOMO Cloud — Distributed Synchronization
Distributed Systems & RealtimeOffline-first between Desktop and MIM Hub (PWA). Optimistic mutations < 8 ms in IndexedDB, FIFO replay, LWW with UUID tie-break, rollback if RLS rejects, and idempotency keys. PostgreSQL policies use real `auth.uid()` — not placeholders.
✦Security Engine — Static JVM Analysis
Application Security & SandboxingStatic bytecode inspection (JARs are never executed): ProcessBuilder, console droppers, JNI, reflection, and sockets. 19 real IOCs (Fracturiser, Necro RAT) with dual SHA-1/SHA-256 hashing. Electron runs with `sandbox`, `contextIsolation`, and `nodeIntegration: false`.
✦NBT Rescue — Binary Data Recovery
Binary Storage & Atomic SwapsNBT v19133 protocol with a zero-data-loss invariant: the original is never overwritten without a `.mim_bak` snapshot on disk. Gzip RFC 1952, `.tmp` buffer, and atomic rename. 12/12 integration tests.
SAGE invariant
“AI must explain evidence, not manufacture it.”
SAGE diagnoses in 0.06 ms with local heuristics. The LLM only translates an already-verified JSON report: if the model fails, the technical verdict is still there.
Event-Driven System Architecture
Total fault isolation through the typed reactive MimEventMap contract:
1. Presentation Layer
Electron 42 (sandbox) · Next.js 16 App Router · MIM Hub PWA
2. Reactive Typed Event Bus
MimEventMap Contract · Fault-Isolated Observers
3. Tiered Persistence
IndexedDB SmartCache · CAS Storage · PostgreSQL (RLS)
All seven engines communicate only through events (`MimEventMap`). None import another: if NBT Rescue sees a damaged file or Aduana an unexpected hash, the failure stays isolated. Hub hardens the perimeter with middleware (HSTS, CSP) and `withApiGuard` (rate limit + Zod) on public routes. Desktop persists BYOK keys with Electron `safeStorage`.
Empirical Measured Benchmarks
Auditable and reproducible metrics validated across headless test suites:
100%
Macro F1-Score
SAGE canonical crash corpus
84%
Top-1 Culprit
Strict root-cause attribution
8×–8.5×
Warm-Cache Speedup
Aduana 1k to 25k scaling
42 ms
Realtime Broadcast
Supabase WebSocket pub/sub
< 8 ms
Optimistic UI Mutation
React 19 + IndexedDB pipeline
0.06 ms
Mean Inference Latency
Per crash log evaluation
* Empirical measurements from headless suites. Reported V8 coverage ~91%. Non-canonical logs degrade to UNKNOWN_RUNTIME.
Product Features & User Experience
Dual-Source Catalog Discovery
Unified search across Modrinth and CurseForge, identifier normalization, and dependency resolution. Default source: both.
MIM-Bot · Model Gateway
BYOK Gemini + OpenRouter, intent routing (text vs multimodal), bully/standard modes, evidence-tagged grounding, and a local heuristic fallback on 429 quota errors.
API Guard · Defense in Depth
Mandatory `withApiGuard`: sliding-window rate limits + Zod. CI fails if a critical route ships unprotected (`lint:api-guard`).
Server Manager · In progress
Desktop `/servers` screen: SFTP audit, SAGE on remote logs, properties/backups/RCON. Multiplayer sync is diagnostic-only — external hosting and client-mod deploy remain open.
JVM Tuning & License Audit
JVM argument presets (ZGC, Shenandoah, G1) and mod redistribution auditing, including Quilt manifests.
Hub PWA · MIM Hub
Standalone Next.js 16 app on Vercel (`apps/hub`): catalog, community, explain/translate, and Edge perimeter. The old `web/` tree is gone.