“A robust system is built on transparent data structures, where process states can be verified at any given moment.”— Software Architecture Review
Operation Model & IPC
The WinNest architecture strictly follows the separation of concerns principle. The Core Engine is written entirely in TypeScript and communicates directly with the host Linux OS and Wine.
When integrating the user interface as a desktop application (Electron GUI), the frontend Renderer Process is prohibited from directly executing Wine commands or mutating prefixes. Instead, all operations are routed through Electron's main-process IPC mechanism to call WinNest Core's shared APIs. This maintains application state integrity and prevents data corruption.
Detailed Directory Structure
Each Windows application is managed independently under the following system path:
├── app.json # Stores installation metadata (ID, Executables, Args)
├── prefix/ # Virtual Wine Prefix directory
│ ├── system.reg # Virtual Windows system Registry
│ ├── user.reg # Virtual Windows user Registry
│ └── drive_c/ # Virtual C:\ drive folder hosting executables
├── installer/ # Cache containing the original software installer
└── logs/ # Structured JSON-line runtime logs (.jsonl)
The configuration file app.json acts as WinNest's central source of truth, tracking target `.exe` execution paths inside the virtual C: drive without rescanning the disk on every startup.
Process Locking (Locks)
To prevent concurrent virtual Registry overrides or file system mutations (Race Conditions), WinNest implements a **Process Locking** mechanism.
When an application begins installation (`install`), repair (`repair`), or startup (`run`), WinNest creates a temporary lock file:
~/.local/share/winnest/apps/<app-id>/.winnest.lock
The lock file stores the Process ID (PID) of the active WinNest process. Before performing any prefix mutations, the Core checks if a lock file exists. If it exists and the written PID remains active on the host Linux kernel, the system rejects the new action and throws a `WinNestError` to safeguard prefix data.