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

44 lines
2.4 KiB
Markdown

# 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 |