# DeepSeek‑Reasonix Desktop Application Architecture Using Wails: A Complete Technical Guide

> Explore the DeepSeek-Reasonix desktop application architecture using Wails. Learn how Go and React TypeScript combine for a real-time AI assistant interface.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: architecture
- Published: 2026-08-13

---

**The DeepSeek‑Reasonix desktop application is built with the Wails framework, combining a native Go backend kernel with a React TypeScript frontend running inside a platform-native webview to deliver a real‑time, event‑driven AI assistant interface.**

Reasonix is a multi‑modal AI assistant that ships as a CLI, TUI, HTTP API, and desktop application. This guide examines the **desktop architecture** as implemented in the [esengine/DeepSeek‑Reasonix](https://github.com/esengine/DeepSeek-Reasonix) repository, focusing on how Wails bridges the shared Go kernel with a modern React UI to produce cross‑platform native binaries.

## Three‑Layer Wails Architecture

The DeepSeek‑Reasonix desktop application follows a strict three‑layer stack: Go kernel, Wails binding layer, and React frontend. Each layer has a single, well‑defined responsibility with explicit interfaces between them.

### Kernel Layer: Shared Go Logic

At the core of Reasonix is the **control.Controller**, a Go struct that implements all business logic—model providers, tool execution, checkpoint persistence, and session memory. This kernel is **not desktop‑specific**; it is imported directly from `internal/control` and shared across the CLI, TUI, and HTTP server variants.

```

internal/boot/build.go          → constructs providers, tools, agent
internal/control/controller.go  → exposes SubmitPrompt, Cancel, etc.

```

The desktop build imports this kernel as a regular Go package. To keep import paths stable across workspace configurations, `reasonix/desktop` uses a relative replacement: `reasonix` → `../`.

### Wails Binding Layer: Go ↔ Webview Bridge

The binding layer exposes kernel methods to the UI and streams events back. Two files define this integration:

- **[`desktop/app.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/app.go)** — Defines the **App** struct with bound methods like `Submit` and `Cancel`
- **[`desktop/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/main.go)** — Configures the Wails runtime, creates the window, and embeds frontend assets

```go
// desktop/app.go
type App struct {
    runtime *wails.Runtime
    ctrl    *control.Controller
}

// Submit is bound to the webview and called from React
func (a *App) Submit(prompt string) (string, error) {
    return a.ctrl.SubmitPrompt(prompt)
}

```

The event flow is bidirectional:

```

React UI ──bridge.ts──▶ Go App.Submit() ──▶ control.Controller
React UI ◀──events──── window.runtime.EventsOn("agent:event")

```

Events emitted by the kernel—chat messages, tool cards, state updates—are received in real time without HTTP round‑trips.

### Frontend Layer: React TypeScript Webview

The UI resides under `desktop/frontend/src` and is built with **Vite**. Key components include:

| Component | Purpose |
|-----------|---------|
| [`Transcript.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/Transcript.tsx) | Renders chat history with tool cards |
| [`Composer.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/Composer.tsx) | Input field for user prompts |
| [`ToolCard.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/ToolCard.tsx) | Visualizes tool execution results |
| [`CodeViewer.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CodeViewer.tsx), [`DiffView.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/DiffView.tsx) | Code display and diff visualization |
| [`bridge.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/bridge.ts) | Abstraction over Wails runtime for Go method calls |

The bridge implementation handles both native Wails mode and browser development mode with automatic fallback to mocks.

```ts
// desktop/frontend/src/lib/bridge.ts
import { invoke } from '@wailsapp/runtime';

export async function submitPrompt(text: string) {
  // Calls App.Submit in the Go backend
  const reply = await invoke<string>('App.Submit', text);
  dispatch({ type: 'RECEIVE_REPLY', payload: reply });
}

```

## Build and Runtime Configuration

### Asset Embedding and Wails Configuration

The production build embeds compiled frontend assets using Go's `embed` directive:

```go
// desktop/main.go
//go:embed all:frontend/dist
var assets embed.FS

```

The [`desktop/wails.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/wails.json) file configures build tags, frontend commands (`pnpm build`), and platform-specific options.

### Platform‑Specific Webview Implementations

| OS | Webview Engine | Configuration |
|----|---------------|---------------|
| Linux | WebKitGTK (default) or WebKitGTK 4.1 | `webkit2_41` build tag |
| Windows | WebView2 | GPU toggle via `REASONIX_DISABLE_WEBVIEW2_GPU` |
| macOS | System WebKit | Hidden title bar with native drag region |

These differences are abstracted in [`desktop/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/main.go), allowing a single codebase to target all three platforms.

## Complete Startup Flow

1. **Binary launch** — [`desktop/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/main.go) initializes the Wails runtime
2. **Kernel construction** — `internal/boot.Build()` creates the shared Controller with all providers and tools
3. **Window creation** — Wails loads embedded assets from `frontend/dist`
4. **Binding registration** — The App instance is exposed to the webview
5. **UI hydration** — React mounts and establishes event listeners
6. **User interaction** — Bridge calls flow to Go; kernel events stream back to update UI state

## Key Files Reference

| File | Role |
|------|------|
| [`desktop/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/main.go) | Entry point, window configuration, asset embedding |
| [`desktop/app.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/app.go) | Bound Go methods exposed to webview |
| [`desktop/wire.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/wire.go) | Event serialization between Go and webview |
| [`desktop/wails.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/wails.json) | Wails project configuration |
| [`desktop/frontend/src/lib/bridge.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/lib/bridge.ts) | TypeScript bridge for Go calls |
| [`desktop/frontend/src/components/Transcript.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/components/Transcript.tsx) | Chat transcript rendering |
| [`internal/control/controller.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/control/controller.go) | Shared kernel implementation |

## Summary

- Reasonix uses **Wails** to combine a Go backend with a React frontend in a native desktop window
- The **control.Controller** kernel is shared across CLI, TUI, HTTP, and desktop variants
- **Bridge pattern** in [`bridge.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/bridge.ts) decouples UI components from Wails runtime details
- **Event streaming** via `runtime.EventsEmit` enables real‑time UI updates without polling
- **Single codebase** targets Linux, Windows, and macOS through platform‑specific webview configurations

## Frequently Asked Questions

### How does the Reasonix desktop app differ from the CLI or TUI versions?

All variants share the identical Go kernel from `internal/control`. The desktop app adds a React UI and Wails runtime; the CLI uses direct stdin/stdout; the TUI uses a terminal UI library. The desktop build imports the kernel as a library package and exposes it through Wails bindings rather than command handlers.

### What happens if I run the frontend code in a regular browser?

The [`bridge.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/bridge.ts) module automatically detects whether Wails runtime is available and falls back to mock implementations. This allows frontend development with hot reload using Vite's dev server without requiring the Go backend to be running.

### How are frontend assets delivered in production builds?

Go's `embed` directive embeds the entire `frontend/dist` directory into the binary. The `//go:embed all:frontend/dist` annotation in [`desktop/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/main.go) ensures all compiled assets are included, making the final executable self‑contained with no external file dependencies.

### Why was Wails chosen over Electron or Tauri for Reasonix?

Wails provides a Go‑first architecture that lets Reasonix reuse its existing kernel without language bridges or separate processes. The Go kernel already powers CLI and HTTP modes, so Wails achieves maximum code reuse while delivering smaller binaries than Electron and avoiding the complexity of a Rust backend rewrite.