# How Modules Are Organized in holaOS: A Complete Guide to the Monorepo Architecture

> Discover how holaOS organizes modules within its Bun workspaces monorepo. Learn about the apps packages and runtime directories. Explore the architecture of holaboss-ai/holaOS.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: architecture
- Published: 2026-08-15

---

**holaOS uses a Bun workspaces-based monorepo with three top-level directories—`apps/`, `packages/`, and `runtime/`—to separate end-user products, shared libraries, and background services.**

Understanding how modules are organized in holaOS is essential for contributors and developers building on the platform. This open-source AI operating system from holaboss-ai structures its codebase as a **monorepo**, leveraging Bun's workspaces feature to enable unified dependency management, cross-package imports, and parallel builds. The architecture cleanly separates concerns between user-facing applications, reusable libraries, and runtime services.

## Top-Level Directory Structure

The holaOS repository divides all source code into three logical folders, each serving a distinct purpose in the system architecture.

### `apps/` — End-User Products

The `apps/` directory contains deliverable products that users interact with directly:

- **`apps/desktop`** — The **Electron desktop client**, combining an Electron shell with a React front-end. This is the primary user interface for holaOS.
- **`apps/docs`** — The **static documentation site**, built with Vite and serving as the knowledge base for the platform.

### `packages/` — Shared Libraries

Reusable code that multiple applications depend on lives in `packages/`:

- **`packages/ui`** — **Tailwind-styled React components** and the icon wrapper (`@/components/ui/icons`) that replaced the removed `lucide-react` package.
- **`packages/app-sdk`** — The **public TypeScript SDK** that external agents use to interact with holaOS programmatically.
- **`packages/editor`** — The editor component, referenced via Vite alias for source-level imports.

### `runtime/` — Background Services

Standalone services powering holaOS functionality:

- **`runtime/api-server`** — REST/GraphQL API server used by the desktop client and external tools.
- **`runtime/state-store`** — **SQLite-backed persistence layer** for workspaces, sessions, memory, and semantic-search indices.
- **`runtime/harness-host`** — Execution environment host for isolated model inference.
- **`runtime/harnesses`** — Individual harness implementations for specific models (π, Claude, etc.).

## Workspace Configuration in [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json)

The root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) declares these workspaces, enabling Bun to manage dependencies across the entire monorepo:

```json
// https://github.com/holaboss-ai/holaOS/blob/main/package.json
{
  "workspaces": [
    "apps/*",
    "packages/*",
    "runtime/api-server",
    "runtime/channel-gateway",
    "runtime/harness-host",
    "runtime/harnesses",
    "runtime/state-store"
  ]
}

```

This configuration provides three critical capabilities:

- **Single-dependency resolution** — One `node_modules` at the root with hoisted shared packages.
- **Cross-package imports** — Workspaces reference each other by package name.
- **Parallel builds** — Turbo orchestrates concurrent builds across workspaces.

## Core Module Details

| Module | Location | Purpose | Entry Point |
|--------|----------|---------|-------------|
| **Desktop app** | `apps/desktop/src` | Electron + React UI with IPC to runtime | [`apps/desktop/vite.config.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/vite.config.ts) |
| **UI library** | `packages/ui/src` | Shared components and icon system | [`packages/ui/tsconfig.json`](https://github.com/holaboss-ai/holaOS/blob/main/packages/ui/tsconfig.json) |
| **App SDK** | `packages/app-sdk/src` | Public API for agent integration | [`packages/app-sdk/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/app-sdk/src/index.ts) |
| **State store** | `runtime/state-store/src` | SQLite persistence with schema in [`store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/store.ts) | [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) |
| **API server** | `runtime/api-server/src` | Backend API for client and tools | `runtime/api-server/src/` |
| **Harness systems** | `runtime/harness-host/src`, `runtime/harnesses/src` | Isolated AI model execution | `runtime/harness-host/src/` & `runtime/harnesses/src/` |

## Module Resolution and Aliasing

The desktop client uses **Vite's alias system** to import source code directly from other workspaces without waiting for compiled output. This enables rapid development with hot module replacement.

In [`apps/desktop/vite.config.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/vite.config.ts), the editor package is aliased to its source entry:

```ts
// https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/vite.config.ts
{
  find: /^@holaboss\/editor$/,
  replacement: path.resolve(__dirname, "../../packages/editor/src/index.ts")
}

```

The UI icon wrapper provides consistent icon access throughout the codebase:

```tsx
import { IconType, makeIcon } from "@/components/ui/icons";

```

These aliases ensure that cross-workspace imports resolve to **single source versions**, with Bun hoisting dependencies to guarantee a **single copy of React** and consistent TypeScript typings across the monorepo.

## Build and Testing Orchestration

Top-level scripts in [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) coordinate development workflows:

```json
// https://github.com/holaboss-ai/holaOS/blob/main/package.json
{
  "scripts": {
    "desktop:install": "bun install",
    "desktop:dev": "bun --elide-lines=0 --filter=holaboss-local run dev",
    "runtime:test": "bun --filter=@holaboss/runtime-state-store run test && bun --filter=@holaboss/runtime-harnesses run test ..."
  }
}

```

- **`turbo`** runs builds concurrently for each workspace.
- Each runtime service maintains its own test suite (e.g., [`runtime/state-store/src/store.test.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.test.ts)).
- The `--filter` flag targets specific workspaces for targeted operations.

## Code Examples: Working with holaOS Modules

### Importing UI Components in the Desktop Client

```tsx
// apps/desktop/src/components/Sidebar.tsx
import { Button } from "@holaboss/ui";
import { makeIcon, IconType } from "@/components/ui/icons";

const SettingsIcon = makeIcon(IconType.Settings);

export function Sidebar() {
  return (
    <nav className="flex flex-col p-4">
      <Button icon={SettingsIcon}>Settings</Button>
    </nav>
  );
}

```

### Using the App SDK for Agent Integration

```ts
import { Hola } from "@holaboss/app-sdk";

async function startChat() {
  const client = new Hola({ apiKey: process.env.HOLA_API_KEY });
  const session = await client.sessions.create({ workspaceId: "root" });
  await client.sessions.run(session.id, { prompt: "Hello, agent!" });
}

```

### Interacting with the State Store

```ts
import { RuntimeStateStore } from "@holaboss/runtime-state-store";

const store = new RuntimeStateStore({ workspaceRoot: "/tmp/workspaces" });
store.db().prepare(`
  INSERT INTO memory_entries (memory_id, workspace_id, scope, memory_type, subject_key, path, title, summary, tags, fingerprint, status, created_at, updated_at)
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
`).run(
  "mem-123",
  "root",
  "workspace",
  "fact",
  "weather",
  "/weather/today",
  "Today's weather",
  "Sunny with a chance of code",
  JSON.stringify(["weather", "code"]),
  "fp-001",
  "active",
  new Date().toISOString(),
  new Date().toISOString()
);

```

*Source: [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) — https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts*

### Launching Development Mode

```bash

# Install dependencies across all workspaces

npm run desktop:install

# Start Electron + Vite with hot module reloading

npm run desktop:dev

```

## Key Files for Module Organization

| File | Purpose |
|------|---------|
| [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) | Root workspace configuration |
| [`apps/desktop/vite.config.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/vite.config.ts) | Vite aliases for cross-workspace imports |
| [`apps/desktop/src/components/ui/icons.tsx`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/src/components/ui/icons.tsx) | Centralized icon wrapper system |
| [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) | State store schema and API |
| [`packages/app-sdk/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/app-sdk/src/index.ts) | SDK public entry point |
| `packages/ui/src/` | UI component library source |
| `runtime/api-server/src/` | API server implementation |
| [`apps/docs/tsconfig.json`](https://github.com/holaboss-ai/holaOS/blob/main/apps/docs/tsconfig.json) | Documentation site configuration |

## Summary

- **holaOS modules are organized in a Bun workspaces monorepo** with three top-level directories: `apps/`, `packages/`, and `runtime/`.
- **Workspaces enable unified dependency management** through single `node_modules` hoisting and cross-package imports by package name.
- **Vite aliases allow source-level imports** between workspaces, eliminating build-step delays during development.
- **The architecture separates concerns cleanly**: user-facing applications, shared libraries, and background services each occupy distinct organizational boundaries.
- **Turbo and Bun scripts orchestrate builds and tests** across the entire monorepo with parallel execution.

## Frequently Asked Questions

### What package manager does holaOS use for its monorepo?

holaOS uses **Bun** as its package manager and runtime, leveraging its native workspaces feature defined in the root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json). Bun provides faster installation, unified dependency resolution, and built-in TypeScript support.

### How do I import code from one workspace into another?

Use the **package name** defined in the target workspace's [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json). For example, import from `packages/ui` using `import { Button } from "@holaboss/ui"`. The desktop client additionally uses **Vite aliases** to import source files directly (e.g., `@holaboss/editor` → [`../../packages/editor/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/../../packages/editor/src/index.ts)).

### Where is the database schema defined in holaOS?

The **SQLite schema** for the state store is defined in [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts). This file contains all table definitions for workspaces, sessions, memory entries, and semantic-search indices used across the platform.

### Can I run individual workspace commands without affecting others?

Yes. Use **Bun's `--filter` flag** to target specific workspaces. For example: `bun --filter=@holaboss/runtime-state-store run test` executes tests only for the state store package. The root [`package.json`](https://github.com/holaboss-ai/holaOS/blob/main/package.json) scripts demonstrate this pattern for common operations.