# crynta/terax-ai architecture

> Architecture diagram of the GitHub repository crynta/terax-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crynta/terax-ai
- Repository: https://github.com/crynta/terax-ai

## Overview

1. Terax is a desktop application with a split architecture: a React/Vite frontend in `src/` and a Rust/Tauri backend in `src-tauri/`. The frontend owns layout, state, and most user interaction; the Rust side provides native capabilities such as PTY, filesystem access, git execution, process control, secrets storage, and platform integration.

2. The app shell is centered around a workspace-oriented IDE layout rather than a single document model. The main UI in `src/app` composes the top-level window, workspace bar, OS/window controls, and workspace surface. Most visible features are mounted as module-level panes, and the workspace/subspace model is the primary unit of context for tabs, terminals, and AI activity.

3. The terminal subsystem is one of the core foundations. On the frontend, `src/modules/terminal` handles pane layout, renderer state, block-based shell interaction, history, completion, drag/drop, and terminal-specific keyboard handling. On the backend, `src-tauri/src/modules/pty` manages native PTY sessions, shell initialization, and agent/shell detection. Data flows from the Rust PTY into the xterm/WebGL renderer and back through user input and command execution.

4. The editor subsystem is another major boundary. `src/modules/editor` wraps CodeMirror 6 with language resolution, themes, Vim mode, autocomplete, diff caches, and file synchronization. It is paired with AI diff views for review/accept/reject workflows. The editor is not a standalone IDE core; it is tightly linked to workspace files, git diffs, and AI-generated edits.

5. File system and project navigation are handled through a dedicated explorer layer. `src/modules/explorer` provides tree rendering, fuzzy search, inline rename, context actions, drag-and-drop, and git status decoration. The Rust backend exposes file/tree/search/watch/mutate operations under `src-tauri/src/modules/fs`, so the frontend can read, search, and change project files while keeping native file watching and mutation centralized.

6. Git/source control is split between frontend orchestration and backend command execution. The Rust `src-tauri/src/modules/git` package wraps git commands, parsing, operations, and process utilities. The frontend source-control and history modules present branch state, staged/unstaged changes, commit flows, and a commit graph view. The data flow is: native git command output -> parsed Rust types -> UI panels and graph rendering.

7. AI is a first-class subsystem, not just a chat widget. `src/modules/ai` contains chat UI, composer, agent registry, snippet/file/context picking, tool approvals, mini-window behavior, sessions, model preferences, transport, redaction/security, speech-to-text, and persistence stores. It also defines tool adapters for filesystem, shell, terminal, search, edits, subagents, and todos. The architecture supports both BYOK cloud providers and local endpoints, with key material stored in the OS keychain via the Rust/native layer.

8. Agent handling is separated from generic chat. The `agents` modules manage agent definitions, notifications, routing, review flows, and store state; `ai/agents` includes subagent execution and registry logic. This lets Terax treat “agent runs” as durable activities with status, notifications, and reviewable output, rather than ephemeral chat messages.

9. The preview, history, and source-control areas extend the “dev workspace” concept beyond editing. `src/modules/preview` auto-detects local servers and opens them in a preview pane, while the git-history module renders a commit graph and remote URL links. These features depend on project context and native process/state knowledge, but are presented as separate panes in the same workspace surface.

10. Global application concerns are handled through smaller cross-cutting modules: `theme` manages app/editor themes and background images; `spaces` persists workspace collections and active-space state; `tabs` manages tab identity, ordering, and window title; `statusbar`, `header`, and `sidebar` provide shared chrome; `shortcuts` centralizes global keybindings; `settings` opens a separate settings window. These modules define how the desktop workspace behaves across panes.

11. The Rust backend is organized as capability modules exposed to the frontend through Tauri commands/events. In addition to FS, git, and PTY, it includes history parsing, network/process helpers, secrets, workspace handling, and shell/agent support. This backend is the trust boundary for native operations: the UI requests actions, and Rust performs the privileged work.

12. The repository also contains a separate settings app entrypoint and native packaging/tooling. `src/settings` is a distinct React app for configuration, while `src-tauri` contains platform manifests, icons, entitlements, installer hooks, and capability definitions. Build and release automation is handled by GitHub Actions plus Nix/flake files, which matter mainly for reproducible packaging across macOS, Linux, and Windows.

Main entry points: [`src/app/App.tsx`](https://github.com/crynta/terax-ai/blob/main/src/app/App.tsx) (App shell), [`src/modules/ai/index.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/index.ts) (AI), [`src/modules/source-control/index.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/source-control/index.ts) (Source control), [`.github/workflows/release.yml`](https://github.com/crynta/terax-ai/blob/main/.github/workflows/release.yml) (Build & release)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React UI"]
  node_app_shell["App shell<br/>react shell<br/>[App.tsx]"]
  node_workspace_model["Workspaces<br/>state model<br/>[index.ts]"]
  node_tabs["Tab system<br/>navigation<br/>[index.ts]"]
  node_terminal["Terminal<br/>pane runtime<br/>[index.ts]"]
  node_editor["Editor<br/>code editing<br/>[index.ts]"]
  node_explorer["Explorer<br/>project tree<br/>[index.ts]"]
  node_git_ui["Source control<br/>git ui<br/>[index.ts]"]
  node_history_ui["Git history<br/>graph view<br/>[index.ts]"]
  node_preview["Preview<br/>[index.ts]"]
  node_ai["AI<br/>assistant runtime<br/>[index.ts]"]
  node_agents["Agents<br/>agent orchestration<br/>[index.ts]"]
  node_theme["Theme<br/>appearance<br/>[index.ts]"]
  node_chrome["App chrome<br/>window ui<br/>[index.ts]"]
end

subgraph group_backend["Rust backend"]
  node_pty["PTY<br/>native terminal<br/>[mod.rs]"]
  node_fs["Filesystem<br/>native fs<br/>[mod.rs]"]
  node_git_native["Git native<br/>native git<br/>[mod.rs]"]
  node_history_native["History parse<br/>native parsing<br/>[mod.rs]"]
  node_workspace_native["Workspace native<br/>native workspace<br/>[workspace.rs]"]
  node_secrets["Secrets<br/>keychain bridge<br/>[secrets.rs]"]
end

subgraph group_settings["Settings app"]
  node_settings_app["Settings app<br/>react settings<br/>[SettingsApp.tsx]"]
end

subgraph group_tooling["Build & release"]
  node_build_release["Build & release<br/>tooling<br/>[release.yml]"]
end

node_app_shell -->|"composes"| node_chrome
node_app_shell -->|"uses"| node_workspace_model
node_app_shell -->|"coordinates"| node_tabs
node_app_shell -->|"mounts"| node_terminal
node_app_shell -->|"mounts"| node_editor
node_app_shell -->|"mounts"| node_explorer
node_app_shell -->|"mounts"| node_git_ui
node_app_shell -->|"mounts"| node_history_ui
node_app_shell -->|"mounts"| node_preview
node_app_shell -->|"mounts"| node_ai
node_app_shell -->|"mounts"| node_agents
node_terminal -->|"streams"| node_pty
node_terminal -->|"session context"| node_workspace_native
node_editor -->|"reads/writes"| node_fs
node_editor -->|"diffs against"| node_git_ui
node_explorer -->|"browses"| node_fs
node_explorer -->|"decorates"| node_git_ui
node_git_ui -->|"executes"| node_git_native
node_history_ui -->|"renders"| node_history_native
node_ai -->|"stores keys"| node_secrets
node_ai -->|"tools"| node_fs
node_ai -->|"tools"| node_pty
node_ai -->|"tools"| node_git_native
node_ai -->|"routes runs"| node_agents
node_settings_app -->|"configures"| node_secrets
node_theme -->|"styles"| node_app_shell
node_build_release -->|"packages"| node_app_shell
node_build_release -->|"packages"| node_settings_app
node_build_release -->|"bundles"| node_pty

click node_app_shell "https://github.com/crynta/terax-ai/blob/main/src/app/App.tsx"
click node_workspace_model "https://github.com/crynta/terax-ai/blob/main/src/modules/spaces/index.ts"
click node_tabs "https://github.com/crynta/terax-ai/blob/main/src/modules/tabs/index.ts"
click node_terminal "https://github.com/crynta/terax-ai/blob/main/src/modules/terminal/index.ts"
click node_editor "https://github.com/crynta/terax-ai/blob/main/src/modules/editor/index.ts"
click node_explorer "https://github.com/crynta/terax-ai/blob/main/src/modules/explorer/index.ts"
click node_git_ui "https://github.com/crynta/terax-ai/blob/main/src/modules/source-control/index.ts"
click node_history_ui "https://github.com/crynta/terax-ai/blob/main/src/modules/git-history/index.ts"
click node_preview "https://github.com/crynta/terax-ai/blob/main/src/modules/preview/index.ts"
click node_ai "https://github.com/crynta/terax-ai/blob/main/src/modules/ai/index.ts"
click node_agents "https://github.com/crynta/terax-ai/blob/main/src/modules/agents/index.ts"
click node_theme "https://github.com/crynta/terax-ai/blob/main/src/modules/theme/index.ts"
click node_chrome "https://github.com/crynta/terax-ai/blob/main/src/modules/header/index.ts"
click node_pty "https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/pty/mod.rs"
click node_fs "https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/fs/mod.rs"
click node_git_native "https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/git/mod.rs"
click node_history_native "https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/history/mod.rs"
click node_workspace_native "https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs"
click node_secrets "https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs"
click node_settings_app "https://github.com/crynta/terax-ai/blob/main/src/settings/SettingsApp.tsx"
click node_build_release "https://github.com/crynta/terax-ai/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_workspace_model,node_tabs,node_terminal,node_editor,node_explorer,node_git_ui,node_history_ui,node_preview,node_ai,node_agents,node_theme,node_chrome toneBlue
class node_pty,node_fs,node_git_native,node_history_native,node_workspace_native,node_secrets toneAmber
class node_settings_app toneMint
class node_build_release toneRose
```

## Components

### React UI

Main desktop application and feature modules in src/

- [App shell](https://github.com/crynta/terax-ai/blob/main/src/app/App.tsx): react shell · Top-level window layout, workspace surface, and chrome composition · `src/app/App.tsx`
- [Workspaces](https://github.com/crynta/terax-ai/blob/main/src/modules/spaces/index.ts): state model · Workspace collections, active space, and persistence · `src/modules/spaces/index.ts`
- [Tab system](https://github.com/crynta/terax-ai/blob/main/src/modules/tabs/index.ts): navigation · Tab identity, ordering, and window title coordination · `src/modules/tabs/index.ts`
- [Terminal](https://github.com/crynta/terax-ai/blob/main/src/modules/terminal/index.ts): pane runtime · Block-based terminal panes, renderer state, input, and session wiring · `src/modules/terminal/index.ts`
- [Editor](https://github.com/crynta/terax-ai/blob/main/src/modules/editor/index.ts): code editing · CodeMirror-based editor panes, language support, themes, Vim, and file sync · `src/modules/editor/index.ts`
- [Explorer](https://github.com/crynta/terax-ai/blob/main/src/modules/explorer/index.ts): project tree · File tree, search, rename, drag-and-drop, and git decoration · `src/modules/explorer/index.ts`
- [Source control](https://github.com/crynta/terax-ai/blob/main/src/modules/source-control/index.ts): git ui · Commit, branch, staged/unstaged views, and source-control orchestration · `src/modules/source-control/index.ts`
- [Git history](https://github.com/crynta/terax-ai/blob/main/src/modules/git-history/index.ts): graph view · Commit graph and history pane for repository exploration · `src/modules/git-history/index.ts`
- [Preview](https://github.com/crynta/terax-ai/blob/main/src/modules/preview/index.ts): web preview · Local server detection and embedded preview pane · `src/modules/preview/index.ts`
- [AI](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/index.ts): assistant runtime · Chat, composer, tools, sessions, models, approvals, and persistence · `src/modules/ai/index.ts`
- [Agents](https://github.com/crynta/terax-ai/blob/main/src/modules/agents/index.ts): agent orchestration · Durable agent definitions, notifications, routing, and review flows · `src/modules/agents/index.ts`
- [Theme](https://github.com/crynta/terax-ai/blob/main/src/modules/theme/index.ts): appearance · App/editor themes, backgrounds, and surface styling · `src/modules/theme/index.ts`
- [App chrome](https://github.com/crynta/terax-ai/blob/main/src/modules/header/index.ts): window ui · Header, sidebar, status bar, workspace switcher, and shortcuts · `src/modules/header/index.ts`

### Rust backend

Tauri native capability layer in src-tauri/

- [PTY](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/pty/mod.rs): native terminal · Native pseudo-terminal sessions, shell initialization, and agent/shell detection · `src-tauri/src/modules/pty/mod.rs`
- [Filesystem](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/fs/mod.rs): native fs · Tree, search, watch, file access, and mutations exposed to the UI · `src-tauri/src/modules/fs/mod.rs`
- [Git native](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/git/mod.rs): native git · Git command execution, parsing, operations, and process helpers · `src-tauri/src/modules/git/mod.rs`
- [History parse](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/history/mod.rs): native parsing · Repository history parsing used by the UI commit graph · `src-tauri/src/modules/history/mod.rs`
- [Workspace native](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs): native workspace · Native workspace/process/context helpers and shell support · `src-tauri/src/modules/workspace.rs`
- [Secrets](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs): keychain bridge · OS-backed secret storage for provider keys and native credentials · `src-tauri/src/modules/secrets.rs`

### Settings app

Separate configuration entrypoint and preferences UI

- [Settings app](https://github.com/crynta/terax-ai/blob/main/src/settings/SettingsApp.tsx): react settings · Dedicated settings entrypoint for configuration and preferences · `src/settings/SettingsApp.tsx`

### Build & release

Packaging, CI, and reproducible build tooling

- [Build & release](https://github.com/crynta/terax-ai/blob/main/.github/workflows/release.yml): tooling · CI workflows, Nix packaging, and Tauri platform configuration · `.github/workflows/release.yml`

## Connections

- App shell → App chrome: composes · The shell assembles shared desktop chrome around the workspace surface
- App shell → Workspaces: uses · The shell renders and switches active workspaces
- App shell → Tab system: coordinates · Top-level navigation and window title follow tab state
- App shell → Terminal: mounts · Terminal panes are placed into the workspace surface
- App shell → Editor: mounts · Editor panes are placed into the workspace surface
- App shell → Explorer: mounts · Project navigation is part of the workspace layout
- App shell → Source control: mounts · Source control is exposed as a workspace pane
- App shell → Git history: mounts · Commit history is exposed as a workspace pane
- App shell → Preview: mounts · Local preview is shown inside the workspace surface
- App shell → AI: mounts · AI chat and tools are part of the main workspace
- App shell → Agents: mounts · Agent activity and notifications are surfaced in the app
- Terminal → PTY: streams · Terminal UI exchanges shell input/output with native PTY sessions
- Terminal → Workspace native: session context · Terminal sessions follow workspace and shell context
- Editor → Filesystem: reads/writes · Editors synchronize document contents with project files
- Editor → Source control: diffs against · Editor review flows are driven by git changes
- Explorer → Filesystem: browses · The file tree and search come from native filesystem access
- Explorer → Source control: decorates · File rows show git status and change state
- Source control → Git native: executes · UI actions are backed by native git commands and parsing
- Git history → History parse: renders · Commit graph data is built from native history parsing
- AI → Secrets: stores keys · Provider credentials are persisted through the OS keychain bridge
- AI → Filesystem: tools · AI can inspect and edit workspace files through native FS tools
- AI → PTY: tools · AI shell and terminal tools depend on native PTY sessions
- AI → Git native: tools · AI can reason about and act on repository state via git commands
- AI → Agents: routes runs · Agent execution and review flows are coordinated with the agent subsystem
- Settings app → Secrets: configures · Settings UI manages provider keys and stored preferences
- Theme → App shell: styles · Theme state influences the overall desktop surface
- Build & release → App shell: packages · The frontend app is built and released through project tooling
- Build & release → Settings app: packages · The settings entrypoint is included in the release pipeline
- Build & release → PTY: bundles · Native backend capabilities are compiled and packaged with the desktop app