Repository architecture

Top-level map

molt/
├── .github/workflows/          # macOS CI and release automation
├── src/                        # React and TypeScript frontend
├── src-tauri/                  # Rust backend, Tauri config, resources, icons
├── tests/python/               # Subprocess-level Python kernel tests
├── index.html                  # Main-window Vite entry
├── settings.html               # Settings-window Vite entry
├── package.json                # npm scripts and frontend dependencies
├── vite.config.ts              # Multi-entry frontend build
├── README.md                   # User and development overview
├── CONTRIBUTING.md             # Development workflow and runtime boundaries
└── AGENTS.md                   # Repository-agent guidance

Layered runtime

Molt is a three-layer desktop application built with Tauri v2:

• The React and TypeScript frontend renders the two windows, owns notebook state, edits Python with CodeMirror, coordinates execution, and schedules notebook saves.
• The Rust backend owns filesystem access, configuration, native windows and menus, process lifecycle, and the typed Tauri command boundary.
• One bundled, standard-library-only Python server runs per active tab and owns that tab’s persistent execution namespace.

The main and settings windows have separate HTML and React entry points in one Vite build. The main window never opens a Python pipe directly; it uses the typed wrappers in src/services/backend.ts to invoke Rust commands.

Cell source in CodeMirror
  → frontend execution coordinator
  → Tauri command
  → Rust per-tab request queue
  → newline-delimited JSON on child stdin
  → Python execution and final-expression evaluation
  → newline-delimited JSON on child stdout
  → Rust response deserialization
  → frontend output records and cell state

Frontend boundaries

Application and windows

Path	Responsibility
src/main.tsx	Mount main React application.
src/App.tsx	Persistence gate, warning banner, initial/lazy kernels, global shortcuts, appearance synchronization.
src/settings-main.tsx	Mount settings application.
src/pages/Settings.tsx	Load, preview, edit, and save configuration.

Notebook interface

Path	Responsibility
src/components/TabBar.tsx	Render fixed tabs 1–4.
src/components/Toolbar.tsx	Kernel state, Clear, Run All, Restart, and Stop.
src/components/Notebook.tsx	Render ordered cells and insertion controls.
src/components/Cell.tsx	CodeMirror editor, execution binding, run/interrupt control, cell hover controls.
src/components/CellOutput.tsx	Render stdout, stderr, and error text.

State and orchestration

Path	Responsibility
src/store/notebookStore.ts	Four notebooks, cell mutations, transient execution state, persisted-state restoration.
src/services/backend.ts	Typed Tauri command wrappers.
src/services/execution.ts	Per-tab reservations, single-cell and Run All sequencing, cancellation, and lifecycle.
src/services/persistence.ts	File validation, serialization, deduplication, and ordered save coordination.
src/hooks/usePersistence.ts	React lifecycle for initial load, subscriptions, errors, and unmount flushing.
src/types/notebook.ts	Shared frontend data contracts.

Presentation

Path	Responsibility
src/styles.css	Fixed light palette, effects-on/off surfaces, controls, output colors, typography, motion.
src/theme/codemirror.ts	Editor CSS mapping and Python token highlight roles.

Rust backend boundaries

Path	Responsibility
src-tauri/src/main.rs	Desktop entry point that calls the library runner.
src-tauri/src/lib.rs	Tauri construction, native menus, settings window, vibrancy, managed state, shutdown cleanup.
src-tauri/src/commands.rs	Public Tauri command functions.
src-tauri/src/config.rs	TOML model, defaults, file I/O, interpreter validation, resource path.
src-tauri/src/kernel.rs	Child processes, per-tab queues, protocol I/O, interrupt, restart, stop, shutdown.
src-tauri/src/persistence.rs	Raw notebooks.json loading and atomic saving.
src-tauri/src/storage.rs	Application Support paths and atomic file replacement.
src-tauri/tauri.conf.json	Window, bundle, resource, build, and minimum-system settings.
src-tauri/Info.plist	macOS LSUIElement setting.
src-tauri/capabilities/default.json	Main/settings window permissions.

Python boundary

src-tauri/resources/kernel_server.py is a pure-standard-library line-oriented server. Keep it independent of packages not guaranteed in the user’s selected interpreter.

Its stdout is protocol-only. Debug text written there corrupts responses. Rust drains direct process stderr to prevent a full pipe from blocking the kernel; those native writes are not returned as cell output.

Critical cross-layer contracts

Changes to these surfaces require coordinated tests and documentation:

• Kernel request and response field names.
• Tauri command names, JavaScript argument names, and Rust return serialization.
• KernelState values in Rust and TypeScript.
• Persisted notebook schema.
• Configuration JSON/TOML field names.
• Cell output types and renderer behavior.
• Window labels main and settings.
• Resource path for kernel_server.py.

Use the detailed runtime data model, kernel protocol, and Tauri command API when changing these boundaries.

Data-flow example

CodeMirror edit
  → Zustand updateCellSource
  → debounce snapshot extraction
  → invoke save_notebooks
  → Rust direct JSON file write

Cell run
  → executeSingleCell
  → ensure_kernel
  → execute_cell
  → per-tab Rust queue
  → Python JSON line
  → result JSON line
  → frontend CellOutput records

Window and lifecycle integration

The Tauri configuration creates a visible, transparent, decorated main window. Rust builds the Molt, File, Edit, and Window menus and creates the settings window on demand. The bundle also sets LSUIElement, so it has no Dock icon, but the selected release does not implement a tray controller or main-window reopen path.

The kernel manager captures the interpreter when the app is constructed. Saving a new interpreter does not mutate that manager, which is why the user must relaunch. Clear stops the managed process before replacing the tab with one empty cell. On app exit, Rust drains the kernel map and terminates tracked child processes.

Source-of-truth caution

Use the released implementation, tests, manifests, current README.md, CONTRIBUTING.md, and AGENTS.md as evidence. Retired specifications and design notes remain only in Git history and are not release requirements.