System overview

Voktty is a two-process desktop application with a thin React shell over a Rust host.

+-----------------------------+       invoke / events       +------------------------------+
| React 19 webview             | <--------------------------> | Tauri 2 Rust host             |
|                             |                              |                              |
| tabs, panes, editor, AI UI  |                              | PTY, filesystem, Git, shell  |
| xterm.js, CodeMirror        |                              | network, secrets, LSP, WSL    |
+-----------------------------+                              +------------------------------+
             |                                                               |
             | local state and rendering                                    | OS resources
             v                                                               v
       browser-like webview                                           processes, files, sockets

Entry points

  • src/main.tsx mounts the React application.
  • src/App.tsx coordinates modules and mounts shared providers.
  • src/settings/main.tsx mounts the separate Settings window.
  • src-tauri/src/main.rs and src-tauri/src/lib.rs initialize the native host, plugins and commands.

Frontend organization

The frontend is organized into self-contained modules under src/modules/. Each module owns UI, pure helpers, bridges and tests where appropriate. App.tsx composes module boundaries but should not become the home for feature-specific business logic.

Important modules include:

Module Responsibility
terminal xterm lifecycle, renderer pool, PTY bridge and OSC handlers.
editor CodeMirror, language registry, saves, formatting, LSP and completion.
tabs Tab union, active tab and split layout.
workspace Local, WSL and remote environment selection.
explorer File tree, search, watches and attachments.
source-control and git-history Git status, diffs, commits and graph.
ai Providers, sessions, composer, tools, approvals and diffs.
extensions Extension discovery, lifecycle and the voktty API.
theme CSS variables, presets, custom themes and editor pairing.

Native modules

Rust modules own operating-system access. Tauri commands are registered from src-tauri/src/lib.rs and grouped by domain under src-tauri/src/modules/. The host also owns process groups, Windows Job Objects, network classification, keychain access and protocol framing.

Design constraints

  • The webview never touches the filesystem, shells or secrets directly.
  • New core logic belongs in pure, dependency-light functions where possible.
  • Unused features should not create processes, IPC traffic or eager bundle cost.
  • Every security boundary validates at the native boundary, even if the frontend already validates the same input.
  • A core subsystem change needs a test that locks its invariant.

Source of truth

VOKTTY.md is the living architecture document. These pages explain it for readers and should link back to the relevant source files instead of creating a competing contract.