Lutra/docs/architecture.md
danny 1fc46daa8e M0: import starter package (rules, roadmap, progress docs)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 20:22:22 +02:00

2.4 KiB

Architecture

Status: draft, to be completed in M0 · Last updated: 2026-10-13

Overview

apps/lutra-desktop  (L6)  Tauri 2 shell: windows, menus, IPC bridge to the engine
ui/                 (L6)  Vue 3 + TypeScript + Vite frontend, Pinia, CodeMirror 6
apps/lutra-cli      (L5)  the `lutra` command: open, diff, --wait, mcp, perf, bench
crates/control      (L5)  JSON-lines control channel (--control PORT)
crates/mcp          (L5)  MCP server over stdio
crates/engine       (L4)  command registry, workspace state, guard, recovery journal
crates/lsp          (L3)  LSP client (Phpactor first), later DAP client
crates/index        (L2)  symbol index, usages, later type inference
crates/vfs          (L2)  project model, file watching, ignore rules, encodings
crates/search       (L2)  find in files (ignore + grep-searcher crates)
crates/syntax       (L1)  tree-sitter parsing (PHP first), outlines, highlight tokens
crates/text         (L0)  rope buffer, positions, UTF-8/UTF-16 conversion, edits
crates/testkit      (—)   test helpers and fixtures, tests only
xtask               (—)   ci, layers, assets, cleanroom, dev, fixtures

A crate may depend only on crates of a lower layer. cargo xtask layers checks it. Nothing below L6 depends on Tauri or the frontend.

Commands

Every user-visible action is a command: id, label, menu_path, default_shortcut, params (documented schema), enabled(&State) -> bool, run(&mut State, Params) -> Result<Output, EngineError>. Menus, the palette, keymaps, the CLI, the control channel and MCP all call the registry. Long-running commands report progress and can be cancelled.

Frontend ↔ engine

The frontend calls run(id, params) over Tauri IPC and subscribes to state events (open buffers, diagnostics, tree changes). Buffer contents live in the engine; CodeMirror sends edits as transactions and receives authoritative changes back. Theme tokens are defined in Rust and exported as CSS variables.

Open questions for M0

  • Highlighting: tree-sitter tokens from the core vs. a Lezer grammar in CodeMirror for instant highlighting (tree-sitter stays the structural source either way).
  • Git library: gix (preferred, MIT/Apache) vs. alternatives.
  • Terminal: portable-pty in the core, xterm.js in the frontend.

Revision history

Date Change Summary
2026-10-13 major Initial draft