# teoritty/xquakshell architecture

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

- Interactive diagram: https://gitdiagram.com/teoritty/xquakshell
- Repository: https://github.com/teoritty/xquakshell

## Overview

xQuakShell is a portable remote-access desktop application: users unlock an encrypted vault, select a saved connection, and open a tab for an SSH or plugin-provided session; they can then use terminal, file-transfer, and forwarding capabilities. The frontend also manages local-terminal tabs, plugins, trust prompts, settings, and audit history. The README documents these product capabilities, while sampled frontend excerpts show session orchestration and tab routing. Backend internals are only partly sampled, so several UI-to-backend and unsampled subsystem links are marked unverified.

Main entry points: [`frontend/src/actions/sessionActions.ts`](https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/sessionActions.ts) (Session orchestration), [`frontend/src/App.svelte`](https://github.com/teoritty/xquakshell/blob/main/frontend/src/App.svelte) (Desktop workspace), [`internal/usecase/session_lifecycle_service.go`](https://github.com/teoritty/xquakshell/blob/main/internal/usecase/session_lifecycle_service.go) (Session services), [`frontend/src/actions/tabActions.ts`](https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/tabActions.ts) (Tab routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_app["Desktop workspace<br/>[App.svelte]"]
  node_state["Application state<br/>[appState.ts]"]
  node_events["Runtime events<br/>[subscribe.ts]"]
  node_tabs["Tab routing<br/>[tabActions.ts]"]
end

subgraph group_access["Connections and sessions"]
  node_connections["Connection management"]
  node_session_actions["Session orchestration<br/>[sessionActions.ts]"]
  node_session_api["Session API<br/>[sessions.ts]"]
  node_session_backend["Session services"]
  node_terminal["Terminal sessions<br/>[terminalPool.ts]"]
  node_file_transfer["SFTP and transfers<br/>[client.go]"]
  node_local_terminal["Local terminal"]
end

subgraph group_extensions["Plugin platform"]
  node_plugin_ui["Plugin management UI"]
  node_plugin_manager["Plugin management<br/>[plugin_manager.go]"]
  node_plugin_runtime["Plugin process and IPC<br/>[process_host.go]"]
end

subgraph group_security["Vault and trust"]
  node_vault_ui["Vault interface<br/>[VaultUnlock.svelte]"]
  node_vault_storage[("Encrypted vault storage<br/>[storage.go]")]
  node_host_trust["Host-key verification<br/>[ssh_stack.go]"]
  node_audit[("Audit log<br/>[repository.go]")]
end

subgraph group_operations["Operations and settings"]
  node_settings["Settings and locale<br/>[settingsActions.ts]"]
  node_log_window["Audit log viewer<br/>[manager.go]"]
  node_backend["Desktop backend<br/>[app.go]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"gates workspace"| node_vault_ui
node_app -->|"opens sessions"| node_session_actions
node_app -->|"routes tab actions"| node_tabs
node_session_actions -->|"opens and closes"| node_session_api
node_session_actions -->|"updates session state"| node_state
node_tabs -->|"closes sessions"| node_session_actions
node_tabs -->|"closes local tabs"| node_local_terminal
node_session_actions -->|"transfers terminal"| node_terminal
node_events -->|"updates from events"| node_state
node_user -->|"configures access"| node_connections
node_user -->|"transfers files"| node_file_transfer
node_session_api -.->|"calls backend"| node_backend
node_backend -.->|"dispatches sessions"| node_session_backend
node_session_backend -.->|"serves terminal sessions"| node_terminal
node_user -->|"opens local tab"| node_local_terminal
node_user -->|"manages plugins"| node_plugin_ui
node_plugin_ui -.->|"requests installation"| node_plugin_manager
node_plugin_manager -.->|"starts plugin process"| node_plugin_runtime
node_plugin_runtime -.->|"contributes protocols"| node_session_backend
node_user -->|"unlocks vault"| node_vault_ui
node_vault_ui -.->|"unlocks encrypted data"| node_vault_storage
node_session_backend -.->|"verifies host keys"| node_host_trust
node_user -->|"changes preferences"| node_settings
node_user -->|"reviews audit log"| node_log_window
node_log_window -.->|"reads audit records"| node_audit

click node_app "https://github.com/teoritty/xquakshell/blob/main/frontend/src/App.svelte"
click node_state "https://github.com/teoritty/xquakshell/blob/main/frontend/src/stores/appState.ts"
click node_events "https://github.com/teoritty/xquakshell/blob/main/frontend/src/events/subscribe.ts"
click node_tabs "https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/tabActions.ts"
click node_connections "https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/ConnectionDetails.svelte"
click node_session_actions "https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/sessionActions.ts"
click node_session_api "https://github.com/teoritty/xquakshell/blob/main/frontend/src/api/sessions.ts"
click node_session_backend "https://github.com/teoritty/xquakshell/blob/main/internal/usecase/session_lifecycle_service.go"
click node_terminal "https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/terminalPool.ts"
click node_file_transfer "https://github.com/teoritty/xquakshell/blob/main/internal/infra/sftp/client.go"
click node_local_terminal "https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/localTerminalActions.ts"
click node_plugin_ui "https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/plugins/PluginsDialog.svelte"
click node_plugin_manager "https://github.com/teoritty/xquakshell/blob/main/internal/usecase/plugin_manager.go"
click node_plugin_runtime "https://github.com/teoritty/xquakshell/blob/main/internal/infra/plugin/process_host.go"
click node_vault_ui "https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/VaultUnlock.svelte"
click node_vault_storage "https://github.com/teoritty/xquakshell/blob/main/internal/infra/vault/storage.go"
click node_host_trust "https://github.com/teoritty/xquakshell/blob/main/internal/domain/ssh_stack.go"
click node_audit "https://github.com/teoritty/xquakshell/blob/main/internal/infra/auditlog/repository.go"
click node_settings "https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/settingsActions.ts"
click node_log_window "https://github.com/teoritty/xquakshell/blob/main/internal/presentation/logwindow/manager.go"
click node_backend "https://github.com/teoritty/xquakshell/blob/main/app.go"

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,node_state,node_events,node_tabs,node_user toneBlue
class node_connections,node_session_actions,node_session_api,node_session_backend,node_terminal,node_file_transfer,node_local_terminal toneAmber
class node_plugin_ui,node_plugin_manager,node_plugin_runtime toneMint
class node_vault_ui,node_vault_storage,node_host_trust,node_audit toneRose
class node_settings,node_log_window,node_backend toneIndigo
```

## Components

### Workspace

- [Desktop workspace](https://github.com/teoritty/xquakshell/blob/main/frontend/src/App.svelte): `frontend/src/App.svelte`
- [Application state](https://github.com/teoritty/xquakshell/blob/main/frontend/src/stores/appState.ts): `frontend/src/stores/appState.ts`
- [Runtime events](https://github.com/teoritty/xquakshell/blob/main/frontend/src/events/subscribe.ts): `frontend/src/events/subscribe.ts`
- [Tab routing](https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/tabActions.ts): `frontend/src/actions/tabActions.ts`

### Connections and sessions

- [Connection management](https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/ConnectionDetails.svelte): `frontend/src/lib/ConnectionDetails.svelte`
- [Session orchestration](https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/sessionActions.ts): `frontend/src/actions/sessionActions.ts`
- [Session API](https://github.com/teoritty/xquakshell/blob/main/frontend/src/api/sessions.ts): `frontend/src/api/sessions.ts`
- [Session services](https://github.com/teoritty/xquakshell/blob/main/internal/usecase/session_lifecycle_service.go): `internal/usecase/session_lifecycle_service.go`
- [Terminal sessions](https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/terminalPool.ts): `frontend/src/lib/terminalPool.ts`
- [SFTP and transfers](https://github.com/teoritty/xquakshell/blob/main/internal/infra/sftp/client.go): `internal/infra/sftp/client.go`
- [Local terminal](https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/localTerminalActions.ts): `frontend/src/actions/localTerminalActions.ts`

### Plugin platform

- [Plugin management UI](https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/plugins/PluginsDialog.svelte): `frontend/src/lib/plugins/PluginsDialog.svelte`
- [Plugin management](https://github.com/teoritty/xquakshell/blob/main/internal/usecase/plugin_manager.go): `internal/usecase/plugin_manager.go`
- [Plugin process and IPC](https://github.com/teoritty/xquakshell/blob/main/internal/infra/plugin/process_host.go): `internal/infra/plugin/process_host.go`

### Vault and trust

- [Vault interface](https://github.com/teoritty/xquakshell/blob/main/frontend/src/lib/VaultUnlock.svelte): `frontend/src/lib/VaultUnlock.svelte`
- [Encrypted vault storage](https://github.com/teoritty/xquakshell/blob/main/internal/infra/vault/storage.go): `internal/infra/vault/storage.go`
- [Host-key verification](https://github.com/teoritty/xquakshell/blob/main/internal/domain/ssh_stack.go): `internal/domain/ssh_stack.go`
- [Audit log](https://github.com/teoritty/xquakshell/blob/main/internal/infra/auditlog/repository.go): `internal/infra/auditlog/repository.go`

### Operations and settings

- [Settings and locale](https://github.com/teoritty/xquakshell/blob/main/frontend/src/actions/settingsActions.ts): `frontend/src/actions/settingsActions.ts`
- [Audit log viewer](https://github.com/teoritty/xquakshell/blob/main/internal/presentation/logwindow/manager.go): `internal/presentation/logwindow/manager.go`
- [Desktop backend](https://github.com/teoritty/xquakshell/blob/main/app.go): `app.go`

### Other components

- **User**

## Connections

- User → Desktop workspace: uses (evidence: `README.md`)
- Desktop workspace → Vault interface: gates workspace (evidence: `frontend/src/App.svelte`)
- Desktop workspace → Session orchestration: opens sessions (evidence: `frontend/src/App.svelte`)
- Desktop workspace → Tab routing: routes tab actions (evidence: `frontend/src/App.svelte`)
- Session orchestration → Session API: opens and closes (evidence: `frontend/src/actions/sessionActions.ts`)
- Session orchestration → Application state: updates session state (evidence: `frontend/src/actions/sessionActions.ts`)
- Tab routing → Session orchestration: closes sessions (evidence: `frontend/src/actions/tabActions.ts`)
- Tab routing → Local terminal: closes local tabs (evidence: `frontend/src/actions/tabActions.ts`)
- Session orchestration → Terminal sessions: transfers terminal (evidence: `frontend/src/actions/sessionActions.ts`)
- Runtime events → Application state: updates from events (evidence: `frontend/src/events/subscribe.ts`)
- User → Connection management: configures access (evidence: `README.md`)
- User → SFTP and transfers: transfers files (evidence: `README.md`)
- Session API → Desktop backend: calls backend
- Desktop backend → Session services: dispatches sessions
- Session services → Terminal sessions: serves terminal sessions
- User → Local terminal: opens local tab (evidence: `README.md`)
- User → Plugin management UI: manages plugins (evidence: `README.md`)
- Plugin management UI → Plugin management: requests installation
- Plugin management → Plugin process and IPC: starts plugin process
- Plugin process and IPC → Session services: contributes protocols (evidence: `README.md`)
- User → Vault interface: unlocks vault (evidence: `README.md`)
- Vault interface → Encrypted vault storage: unlocks encrypted data
- Session services → Host-key verification: verifies host keys (evidence: `README.md`)
- User → Settings and locale: changes preferences (evidence: `README.md`)
- User → Audit log viewer: reviews audit log (evidence: `README.md`)
- Audit log viewer → Audit log: reads audit records
