> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Electron Desktop Client

> Complete guide to the Olis desktop application

## Overview

The Olis Desktop Client is an Electron-based application that provides a native desktop experience for the Olis AI assistant. It combines Electron's native capabilities with Next.js for a modern React-based UI.

## Technology Stack

<CardGroup cols={2}>
  <Card title="Electron" icon="desktop">
    Native desktop wrapper for cross-platform support
  </Card>

  <Card title="Next.js 14" icon="react">
    React framework with App Router and static export
  </Card>

  <Card title="TypeScript" icon="code">
    Type-safe development across the entire stack
  </Card>

  <Card title="Tailwind CSS" icon="paintbrush">
    Utility-first CSS framework for styling
  </Card>
</CardGroup>

## Project Structure

```bash theme={null}
apps/electron-client/
├── electron/              # Electron main process
│   ├── main.ts           # Main process entry point
│   └── preload.ts        # Preload script for IPC
├── src/
│   ├── app/              # Next.js App Router pages
│   │   ├── page.tsx      # Main chat interface
│   │   └── settings/     # Settings pages
│   ├── components/       # React components
│   └── lib/              # Utilities and helpers
├── native/
│   └── sidecar/          # Rust native module
├── local-llm/            # Bundled llama-server binaries
├── public/               # Static assets
└── release/              # Build artifacts
```

## Development Setup

### Prerequisites

* Node.js 18+
* pnpm 9.15.4+
* Rust (for native sidecar)

### Installation

<Steps>
  <Step title="Navigate to the client directory">
    ```bash theme={null}
    cd apps/electron-client
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```
  </Step>

  <Step title="Build native sidecar">
    ```bash theme={null}
    pnpm run sidecar:build
    ```

    This compiles the Rust native module and copies it to `native/sidecar/index.node`.
  </Step>

  <Step title="Start development server">
    ```bash theme={null}
    pnpm run electron:dev
    ```

    This starts:

    1. Next.js dev server on `http://localhost:3000`
    2. Electron app that loads the dev server
  </Step>
</Steps>

## Available Scripts

<AccordionGroup>
  <Accordion title="Development Scripts">
    ```bash theme={null}
    # Run Next.js dev server only
    pnpm run dev

    # Run Electron + Next.js together (recommended)
    pnpm run electron:dev

    # Build native Rust sidecar
    pnpm run sidecar:build

    # Lint code
    pnpm run lint
    ```
  </Accordion>

  <Accordion title="Production Build Scripts">
    ```bash theme={null}
    # Build Next.js static export
    pnpm run build

    # Compile Electron main process
    pnpm run build:electron

    # Package installers for distribution
    pnpm run package

    # Rebuild native dependencies
    pnpm run install-app-deps
    ```
  </Accordion>
</AccordionGroup>

## Building for Production

<Steps>
  <Step title="Build the renderer">
    ```bash theme={null}
    pnpm run build
    ```

    Creates a static Next.js export in the `out/` directory with:

    * `assetPrefix: "./"` for relative paths
    * `trailingSlash: true` for file:// protocol
    * `output: "export"` for static generation
  </Step>

  <Step title="Compile the main process">
    ```bash theme={null}
    pnpm run build:electron
    ```

    Compiles TypeScript to JavaScript in `dist-electron/`.
  </Step>

  <Step title="Package the application">
    ```bash theme={null}
    pnpm run package
    ```

    Uses electron-builder to create installers in `release/`:

    * Windows: NSIS installer (.exe)
    * macOS: DMG and ZIP
    * Linux: AppImage, Snap, DEB
  </Step>
</Steps>

<Warning>
  **Windows Note**: Stop all running Electron instances before packaging. Running instances can lock `keytar.node` and cause `EPERM` errors during the build.
</Warning>

## Configuration

### Environment Variables

Create a `.env` file in the app root:

```bash theme={null}
# Intent Detection
OLIS_INTENT_MODEL=phi3
OLIS_INTENT_REMOTE_URL=http://localhost:11434
OLIS_INTENT_MODEL_DOWNLOAD_URL=https://example.com/model.gguf
OLIS_INTENT_TIMEOUT_MS=30000

# Document Context
OLIS_DOCS_FOLDER=C:\Users\YourName\Documents\olis-docs

# API Configuration
OLIS_API_URL=http://localhost:8000
```

For production builds, place `.env.production` in the `resources/` directory.

### Next.js Configuration

The `next.config.mjs` is optimized for Electron:

```javascript theme={null}
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',        // Static export
  assetPrefix: './',       // Relative paths for file://
  trailingSlash: true,     // Ensures /page.html works
  images: {
    unoptimized: true      // No Image Optimization API needed
  }
}
```

### Electron Builder Configuration

The `electron-builder.json5` defines package settings:

```json5 theme={null}
{
  "appId": "com.olis.app",
  "productName": "Olis",
  "directories": {
    "output": "release",
    "buildResources": "resources"
  },
  "files": [
    "out/**/*",
    "dist-electron/**/*",
    "native/**/*",
    "local-llm/**/*"
  ],
  "win": {
    "target": ["nsis"],
    "icon": "resources/icon.ico"
  },
  "mac": {
    "target": ["dmg", "zip"],
    "icon": "resources/icon.icns"
  }
}
```

## Features

### Intent Detection

The desktop client supports multiple intent detection backends:

<Tabs>
  <Tab title="Automatic">
    Chooses the best option based on hardware and configuration:

    1. SLM if available and hardware supports it
    2. LLM if remote service is configured
    3. NLP as fallback
  </Tab>

  <Tab title="SLM (Local)">
    Runs a local language model using bundled `llama-server`:

    * Model: GGUF format in `local-llm/` directory
    * No internet required
    * Privacy-focused
    * Slower on weaker hardware
  </Tab>

  <Tab title="LLM (Remote)">
    Uses a hosted language model:

    * Faster responses
    * Requires internet connection
    * Configurable via `OLIS_INTENT_REMOTE_URL`
    * Supports Ollama-compatible APIs
  </Tab>

  <Tab title="NLP (Fallback)">
    Fast heuristic-based detection:

    * Regex patterns
    * Keyword matching
    * No ML required
    * Limited accuracy
  </Tab>
</Tabs>

### Document Context

Users can configure a document folder for context:

```bash theme={null}
OLIS_DOCS_FOLDER=C:\Users\YourName\Documents\olis-docs
```

Supported formats:

* `.txt` - Plain text
* `.md` - Markdown
* `.json` - JSON data
* `.csv` - CSV files

Documents are automatically loaded and used as context for queries.

### Settings Interface

The settings interface provides three main sections:

<CardGroup cols={3}>
  <Card title="General" icon="gear">
    * Theme selection
    * Language preferences
    * Default behaviors
    * Notification settings
  </Card>

  <Card title="Integrations" icon="plug">
    * API connections
    * Third-party services
    * OAuth configurations
    * Webhook settings
  </Card>

  <Card title="Security" icon="shield">
    * Authentication
    * Encryption settings
    * Privacy controls
    * Data retention
  </Card>
</CardGroup>

## Native Sidecar (Rust)

The native sidecar provides high-performance native operations:

```rust theme={null}
// Example: File system operations
#[napi]
pub fn read_file_sync(path: String) -> Result<String> {
  std::fs::read_to_string(path)
    .map_err(|e| Error::from_reason(e.to_string()))
}
```

### Building the Sidecar

```bash theme={null}
cd native/sidecar
cargo build --release

# Copy to correct location
cp ../../target/release/index.node ./
```

### Using in Electron

```typescript theme={null}
// In renderer process
const sidecar = require('./native/sidecar/index.node')
const content = sidecar.readFileSync('/path/to/file.txt')
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Native Module Build Failures">
    **Problem**: Errors building Rust sidecar

    **Solution**:

    ```bash theme={null}
    # Ensure Rust is installed
    rustc --version

    # Clean and rebuild
    cd native/sidecar
    cargo clean
    cargo build --release

    # Copy manually if needed
    cp ../../target/release/index.node ./
    ```
  </Accordion>

  <Accordion title="Electron Packaging Errors">
    **Problem**: `EPERM` error with `keytar.node`

    **Solution**:

    1. Close all Electron instances
    2. Kill any Node processes: `taskkill /F /IM electron.exe` (Windows)
    3. Run `pnpm run install-app-deps`
    4. Try packaging again: `pnpm run package`
  </Accordion>

  <Accordion title="Dev Server Not Loading">
    **Problem**: Electron opens but shows blank window

    **Solution**:

    1. Ensure Next.js dev server is running on port 3000
    2. Check `electron/main.ts` loads correct URL
    3. Open DevTools: `Ctrl+Shift+I` (Windows) or `Cmd+Option+I` (Mac)
    4. Check console for errors
  </Accordion>

  <Accordion title="PowerShell Script Execution">
    **Problem**: PowerShell blocks script execution

    **Solution**:

    ```powershell theme={null}
    # Use .cmd wrapper instead
    pnpm.cmd run electron:dev
    pnpm.cmd run sidecar:build

    # Or enable script execution (admin required)
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Development" icon="code">
    * Use `electron:dev` for hot reloading
    * Test on all target platforms
    * Keep native modules updated
    * Profile performance regularly
  </Card>

  <Card title="Production" icon="rocket">
    * Test packaged builds before release
    * Code sign applications
    * Use auto-update mechanism
    * Monitor crash reports
  </Card>

  <Card title="Security" icon="lock">
    * Enable context isolation
    * Disable Node integration in renderer
    * Validate all IPC messages
    * Use secure storage (keytar)
  </Card>

  <Card title="Performance" icon="gauge">
    * Lazy load components
    * Optimize bundle size
    * Cache expensive operations
    * Use native modules wisely
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Server" icon="server" href="/apps/api-server">
    Learn about the backend API
  </Card>

  <Card title="Intent Detection" icon="lightbulb" href="/features/intent-detection">
    Deep dive into intent detection
  </Card>
</CardGroup>