# What Is the apps/desktop Directory in the Maka Repository? Purpose and Architecture Explained

> Explore the apps/desktop directory in Apache Maka. Understand its purpose as the Electron desktop client and its secure three-layer architecture separating Node, bridge, and React UI.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-08-26

---

**The `apps/desktop` directory contains the complete Electron-based native desktop client for Apache Maka, implementing a secure three-layer architecture that separates the main Node process, a context bridge preload script, and the React renderer UI.**

The `apps/desktop` folder serves as the self-contained workspace for Maka’s desktop application. According to the [apps/desktop/README.md](https://github.com/apache/maka/blob/main/apps/desktop/README.md), this directory encapsulates everything needed to build, package, and run the cross-platform desktop client on macOS and Windows while maintaining strict security boundaries between the UI and system APIs.

## Three-Layer Desktop Architecture

The Maka desktop client follows Electron security best practices by strictly separating concerns across three distinct layers. This architecture prevents the renderer process from directly accessing Node APIs while enabling controlled communication through a tightly managed IPC bridge.

### Main Process: Node/Electron Core

Located in `src/main/`, the **main process** handles OS-level capabilities and application lifecycle management. The entry point at [`src/main/main.ts`](https://github.com/apache/maka/blob/main/src/main/main.ts) enforces a single-instance lock, sets the application name, and bootstraps the Runtime Host. This layer owns window management, native OS integrations, and client-local settings.

### Preload Script: Secure Context Bridge

The [`src/preload/preload.ts`](https://github.com/apache/maka/blob/main/src/preload/preload.ts) file implements the **context bridge** using `contextBridge.exposeInMainWorld('maka', …)`. This single-file layer is the exclusive surface through which the renderer may access Node/Electron APIs. By exposing only specific whitelisted functions via `ipcRenderer.invoke` and `ipcRenderer.send`, the preload script maintains a sandboxed renderer environment while enabling type-safe communication with the main process.

### Renderer Process: React UI

The `src/renderer/` directory contains the **React UI** that executes within the Electron renderer process. Unlike typical Node applications, the renderer never imports `@maka/runtime` directly. Instead, all Node-side interactions route through the `window.maka` object exposed by the preload bridge, ensuring strict security boundaries between untrusted web content and privileged system APIs.

## Key Files and Responsibilities

Understanding the purpose of the `apps/desktop` directory requires examining its critical configuration and source files:

- **[`apps/desktop/package.json`](https://github.com/apache/maka/blob/main/apps/desktop/package.json)**: Defines npm scripts including `npm run dev` for hot-reloading development and declares dependencies for the Electron runtime.
- **[`src/main/main.ts`](https://github.com/apache/maka/blob/main/src/main/main.ts)**: Entry point that configures the application window, registers IPC handlers, and initializes the Runtime Host projection.
- **[`src/preload/preload.ts`](https://github.com/apache/maka/blob/main/src/preload/preload.ts)**: Exposes the typed `window.maka` API to the renderer using Electron’s context bridge.
- **`electron-builder.config.mjs`**: Configures packaging targets for distributable macOS and Windows installers.
- **[`e2e/playwright.config.ts`](https://github.com/apache/maka/blob/main/e2e/playwright.config.ts)**: Configures end-to-end testing infrastructure for the desktop client.

## Development Workflow and macOS Permissions

Developing within the `apps/desktop` directory requires specific build steps and platform considerations. The README outlines a standard workflow for launching the application with hot-module replacement enabled.

To start the desktop client locally:

```bash

# Install dependencies for the workspace

npm install

# Build shared workspace packages

npm run build:workspace-deps

# Launch the Electron app with hot-module replacement

npm run dev

```

For macOS development, the repository handles Transparency, Consent, and Control (TCC) permissions specially. Setting the environment variable `MAKA_DEV_TCC=1` launches an ad-hoc signed application bundle, satisfying macOS TCC requirements during development without requiring full code signing certificates.

## Implementing the Preload Bridge

The security model relies on explicit API exposure through the preload script. Here is the implementation pattern from [`src/preload/preload.ts`](https://github.com/apache/maka/blob/main/src/preload/preload.ts):

```typescript
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('maka', {
  // Example: fetch the application version from the main process
  getAppVersion: () => ipcRenderer.invoke('app:getVersion'),

  // Example: send a fire-and-forget command to the main process
  openUrl: (url: string) => ipcRenderer.send('app:openUrl', url),
});

```

Renderer components consume this API through the global `window.maka` object:

```tsx
import React from 'react';

export const VersionDisplay = () => {
  const [version, setVersion] = React.useState<string>('');

  React.useEffect(() => {
    // Calls the preload bridge defined above
    window.maka.getAppVersion().then(setVersion);
  }, []);

  return <div>Running Maka desktop v{version}</div>;
};

```

This pattern ensures that React components remain agnostic of Electron internals while maintaining type-safe access to main process functionality.

## Summary

- The **`apps/desktop` directory** houses the complete Electron-based desktop client for Apache Maka, distinct from web or mobile implementations.
- It implements a **three-layer security architecture**: Main (Node process), Preload (context bridge), and Renderer (React UI).
- The **[`src/preload/preload.ts`](https://github.com/apache/maka/blob/main/src/preload/preload.ts)** file exclusively controls IPC exposure, preventing direct Node API access from the renderer.
- The **[`src/main/main.ts`](https://github.com/apache/maka/blob/main/src/main/main.ts)** entry point manages application lifecycle, single-instance locking, and Runtime Host bootstrapping.
- **Development workflows** support hot-reloading via `npm run dev` and handle macOS TCC permissions through environment flags.

## Frequently Asked Questions

### What technology stack powers the Maka desktop application?

The Maka desktop application is built with **Electron** for the native shell and **React** for the user interface. The main process runs Node.js with TypeScript, while the renderer uses React with type-safe IPC communication enforced through Electron’s `contextBridge` API as implemented in [`src/preload/preload.ts`](https://github.com/apache/maka/blob/main/src/preload/preload.ts).

### How does the apps/desktop directory handle security between the UI and system APIs?

Security follows Electron’s recommended **context isolation** pattern. The renderer process cannot directly import Node modules or Electron APIs. Instead, [`src/preload/preload.ts`](https://github.com/apache/maka/blob/main/src/preload/preload.ts) explicitly exposes only required functions via `contextBridge.exposeInMainWorld()`, creating a minimal attack surface. All system interactions—such as opening URLs or reading app versions—traverse this controlled bridge using `ipcRenderer`.

### Why is there a separate preload layer instead of letting the renderer call Electron directly?

The **preload layer** exists to maintain **sandbox integrity**. Modern Electron security guidelines require disabling `nodeIntegration` in renderer processes to prevent XSS vulnerabilities from accessing file systems or native modules. The preload script acts as a trusted intermediary that validates and sanitizes messages between the untrusted React UI and privileged main process, ensuring that only whitelisted operations execute.

### How do I build the desktop app for production distribution?

Production builds use the configuration defined in `electron-builder.config.mjs`. After building workspace dependencies with `npm run build:workspace-deps`, the packaging scripts compile the TypeScript source and bundle the application for target platforms. The Playwright configuration in [`e2e/playwright.config.ts`](https://github.com/apache/maka/blob/main/e2e/playwright.config.ts) supports automated testing of the packaged binary before release.