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

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 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 — Defines the App struct with bound methods like Submit and Cancel
• desktop/main.go — Configures the Wails runtime, creates the window, and embeds frontend assets

// 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	Renders chat history with tool cards
Composer.tsx	Input field for user prompts
ToolCard.tsx	Visualizes tool execution results
CodeViewer.tsx, DiffView.tsx	Code display and diff visualization
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.

// 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:

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

The 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, allowing a single codebase to target all three platforms.

Complete Startup Flow

1. Binary launch — 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	Entry point, window configuration, asset embedding
desktop/app.go	Bound Go methods exposed to webview
desktop/wire.go	Event serialization between Go and webview
desktop/wails.json	Wails project configuration
desktop/frontend/src/lib/bridge.ts	TypeScript bridge for Go calls
desktop/frontend/src/components/Transcript.tsx	Chat transcript rendering
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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}