System Overview

MindMux is an Electron desktop application built around a local-first project brain and a runtime-portable execution layer.

High-level architecture

At a high level, the system is composed of:

1. a React renderer
2. an Electron main process
3. runtime integrations
4. an MCP-backed tool layer
5. local file-backed project storage

Core flow

The typical flow is:

1. The renderer drives user interaction.
2. The main process coordinates sessions, projects, tasks, watchers, and configuration.
3. A selected runtime handles chat or task execution.
4. The runtime uses an MCP tool surface to read and act on project knowledge.
5. Durable outputs land in brain/ and operational state lands in project-local storage.

Responsibility split

Renderer

Owns the user-facing surfaces: sessions, pages, tasks, settings, and navigation.

Main process

Owns orchestration: windows, session lifecycle, watchers, runtime coordination, tasks, notifications, and IPC.

Runtime layer

Owns the model-specific execution path for chat and tasks.

MCP layer

Owns structured project operations and external connector access.

Design intent

Several architectural choices appear repeatedly across the codebase:

• keep durable knowledge file-based
• make sessions and tasks explicit product objects
• isolate runtime-specific behavior behind stable abstractions
• expose structured project context through MCP tools
• preserve local ownership of project knowledge

Why this shape works

MindMux needs to combine:

• desktop filesystem access
• long-lived local state
• model execution
• explicit knowledge structures
• human approval checkpoints

This architecture supports all five without collapsing them into one opaque process.

Product consequence

This architecture allows the app to improve in two dimensions independently:

• the knowledge model can deepen without rewriting runtime integrations
• runtime integrations can change without breaking the project brain