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; partly stale
├── SYSTEM_SPEC.md              # Historical design specification; not release truth
└── AGENTS.md                   # Historical plus repository-agent guidance; partly stale

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.

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

Historical-file caution

SYSTEM_SPEC.md and the project overview in AGENTS.md predate major implementation changes. They still describe ephemeral cells, a tray-controlled panel, no tests, and no completed application. Validate design claims against released code before using them as requirements.