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

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

The root package.json declares these workspaces, enabling Bun to manage dependencies across the entire monorepo:

// 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
UI library	packages/ui/src	Shared components and icon system	packages/ui/tsconfig.json
App SDK	packages/app-sdk/src	Public API for agent integration	packages/app-sdk/src/index.ts
State store	runtime/state-store/src	SQLite persistence with schema in store.ts	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, the editor package is aliased to its source entry:

// 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:

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 coordinate development workflows:

// 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).
• The --filter flag targets specific workspaces for targeted operations.

Code Examples: Working with holaOS Modules

Importing UI Components in the Desktop Client

// 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

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

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

Launching Development Mode

# 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	Root workspace configuration
apps/desktop/vite.config.ts	Vite aliases for cross-workspace imports
apps/desktop/src/components/ui/icons.tsx	Centralized icon wrapper system
runtime/state-store/src/store.ts	State store schema and API
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	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. 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. 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).

Where is the database schema defined in holaOS?

The SQLite schema for the state store is defined in 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 scripts demonstrate this pattern for common operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}