# Expected Directory Structure for DeepSeek-Reasonix: Complete Guide

> Understand the DeepSeek-Reasonix directory structure. Explore internal Go engine, desktop frontend, SDK, and npm packages to optimize your development workflow.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-08-09

---

**DeepSeek-Reasonix organizes its codebase into distinct layers—`internal/` for the core Go engine, `desktop/` for the Wails frontend, `sdk/go/` for embeddable libraries, and `npm/` for Node distribution—enforcing strict import boundaries that prevent frontend code from leaking into business logic.**

The DeepSeek-Reasonix repository follows a purpose-driven layout designed to support cross-platform builds and single-binary distribution. Understanding the expected directory structure is essential for contributors embedding the engine into custom tools or extending the desktop application.

## Top-Level Layout Overview

The repository root separates concerns into seven primary domains. Each top-level directory owns a specific responsibility and maintains strict import rules as defined in [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md).

| Directory | Purpose |
|-----------|---------|
| `internal/` | **Core Go engine** containing business logic, providers, agents, and utilities. |
| `desktop/` | **Desktop frontend** built with Wails and WebView2; consumes `internal/control` only. |
| `sdk/go/` | **Go SDK** exposing a thin client library for embedding Reasonix in other programs. |
| `npm/` | **Node CLI wrapper** distributing pre-built native binaries via npm. |
| `docs/` | Human-readable documentation and GitHub Pages source files. |
| `scripts/` | Release automation, signature verification, and CI helper scripts. |
| `site/` | Static site assets (TypeScript, CSS, images) for documentation generation. |

Additional top-level files include [`README.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/README.md) for installation instructions, [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) for project conventions, `Makefile` for build automation, and [`.goreleaser.yaml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.goreleaser.yaml) for cross-compilation configuration.

## Core Engine Layer (`internal/`)

The `internal/` directory houses the pure business logic of DeepSeek-Reasonix. This layer implements the agent-loop, workspace sandboxing, checkpoint/rewind functionality, and the unified controller that frontends invoke.

Key sub-packages include:

- **`internal/worktree/`** – Workspace handling and file operations sandbox
- **`internal/boot/`** – Initialization and configuration loading
- **`internal/agent/`** – Core agent loop and reasoning implementation
- **`internal/control/`** – The only public-facing internal package that frontends may import

According to the layering rules in [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), no code within `internal/` may import from `desktop/` or other frontend layers. This ensures the engine remains portable across CLI, desktop, and HTTP server contexts.

## Frontend and SDK Components

### Desktop Application (`desktop/`)

The `desktop/` directory contains the Wails-based frontend utilizing WebView2. Platform-specific files such as [`window_state.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/window_state.go) and [`updater_windows.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/updater_windows.go) handle window management and auto-updates.

All UI code calls into `internal/control.Controller` as implemented in [`desktop/workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace.go). The import relationship is strictly one-way: `desktop/` imports `internal/control`, but `internal/` never imports `desktop/`.

### Go SDK (`sdk/go/`)

Located at `sdk/go/`, this directory provides a public API wrapper defined in [`sdk/go/sdk.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/sdk.go). It enables other Go programs to embed the Reasonix engine without directly depending on internal packages.

```go
package main

import (
	"context"
	"log"

	"github.com/esengine/DeepSeek-Reasonix/sdk/go"
)

func main() {
	// Initialize a Reasonix instance with a config file
	r, err := reasonix.New(context.Background(), "reasonix.example.toml")
	if err != nil {
		log.Fatalf("init error: %v", err)
	}
	
	// Run a simple command
	out, err := r.Run("implement the TODOs in main.go")
	if err != nil {
		log.Fatalf("run error: %v", err)
	}
	log.Println("Result:", out)
}

```

## Distribution and Documentation

### Node Wrapper (`npm/`)

The `npm/` directory packages the native binary for Node.js distribution. The wrapper script at [`npm/reasonix/bin/reasonix.js`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/npm/reasonix/bin/reasonix.js) downloads the pre-built static binary and exposes the `reasonix` CLI globally after `npm i -g reasonix`.

### Documentation (`docs/` and `site/`)

User-facing documentation lives in `docs/` as Markdown files, which also serve as the source for the GitHub Pages site. The `site/` directory contains TypeScript configurations and styling assets for the static site generator.

### Release Automation (`scripts/`)

Release validation scripts reside in `scripts/`, including [`validate-cli-release-manifest.sh`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/validate-cli-release-manifest.sh) for artifact verification. These tools enforce project conventions defined in [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) alongside the `repolint` utility.

## Build and CI Configuration

The repository root contains several configuration files critical for building and distribution:

- **`Makefile`** – Provides targets such as `make build` and `make cross` for compilation
- **[`.goreleaser.yaml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.goreleaser.yaml)** – Configures cross-compilation of the single static binary
- **`.github/workflows/`** – Houses CI/CD pipelines for testing, linting, and documentation impact analysis
- **`go.mod` / `go.sum`** – Define Go module dependencies and lock files

End-to-end testing occurs in `prod_test/` and `prod_fast_test/`, validating the complete engine and frontend integration in production-like environments.

## Working with the Repository

### Initializing the Engine via Go SDK

Import the SDK and instantiate a new Reasonix controller with a configuration file:

```go
ctrl, err := reasonix.New(context.Background(), "config.toml")
if err != nil {
    log.Fatal(err)
}
result, err := ctrl.Run("refactor authentication logic")

```

### Running the Desktop Application

Build and run the Wails frontend using the provided Makefile targets. The desktop layer initializes the controller through `internal/control.NewController()` as shown in [`desktop/workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace.go):

```go
ctrl, err := control.NewController()
if err != nil { 
    log.Fatal(err) 
}
ctrl.HandleUserInput("what is the weather tomorrow?")

```

### Installing via npm

After packaging, install the CLI globally:

```bash
npm i -g reasonix
reasonix setup          # configure provider & model

reasonix run "write a Go function that sums ints"

```

### Executing Tests

Run the comprehensive test suite using Make or Go directly:

```bash
make test                 # unit tests + prod_test

go test ./internal/...    # validate core packages only

```

## Summary

- **`internal/`** contains the core Go engine with strict layering rules preventing frontend imports
- **`desktop/`** houses the Wails+WebView2 frontend and exclusively imports `internal/control`
- **`sdk/go/`** provides a public embedding API via [`sdk.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk.go) for third-party Go applications
- **`npm/`** distributes pre-built binaries through a Node.js wrapper script
- **`docs/`** and **`site/`** maintain user documentation and static site generation assets
- **`scripts/`** and **`.github/workflows/`** handle release automation and CI validation

## Frequently Asked Questions

### What is the purpose of the `internal/` directory?

The `internal/` directory contains DeepSeek-Reasonix's core Go engine, including packages for workspace management (`internal/worktree/`), agent logic (`internal/agent/`), and the control interface (`internal/control/`). This directory enforces strict architectural boundaries where frontend code cannot be imported, ensuring business logic remains platform-agnostic and testable across CLI, desktop, and server contexts.

### How does the desktop frontend communicate with the core engine?

The desktop frontend in `desktop/` communicates exclusively through `internal/control.Controller`. As implemented in [`desktop/workspace.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/workspace.go), the UI layer initializes a controller instance and passes user input via methods like `HandleUserInput()`. This one-way import relationship ensures the engine remains decoupled from WebView2 and platform-specific window management code.

### Can I embed DeepSeek-Reasonix in my own Go application?

Yes, through the Go SDK located in `sdk/go/`. The [`sdk.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk.go) file exposes a public API that wraps the internal engine, allowing you to instantiate Reasonix with `reasonix.New()` and execute commands via the `Run()` method without importing internal packages directly. This is the supported method for embedding the engine in external Go programs.

### Where are the release automation scripts located?

Release automation scripts reside in the `scripts/` directory, including artifact validation tools like [`validate-cli-release-manifest.sh`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/validate-cli-release-manifest.sh). The `.github/workflows/` directory contains CI/CD pipelines for continuous integration, while [`.goreleaser.yaml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.goreleaser.yaml) configures cross-platform binary compilation. Together, these tools enforce the conventions defined in [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) during the release process.