# hollaOS Architecture: A Deep Dive into the Modular TypeScript Platform

> Explore the hollaOS architecture a modular TypeScript platform. Understand its runtime state store, harness capabilities, channel gateway, and React UI for robust external integrations.

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

---

**hollaOS is a modular, TypeScript-first platform built around a runtime state store, harness-based capabilities, a channel gateway for external integrations, and a React-based desktop UI.**

This architecture separates persistence, business logic, and presentation into distinct layers. According to the holaboss-ai/holaOS source code, each layer communicates through well-defined interfaces—primarily the **MCP (Model-Controlled Plugin)** system—enabling independent evolution of components.

## Core Architecture Layers

The codebase organizes functionality into seven interconnected layers. Understanding each layer's responsibility and entry point is essential for working with hollaOS effectively.

### State Store Layer

The **state store** ([`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts)) provides the central persistence mechanism for hollaOS. It manages workspaces, sessions, capabilities, and schema migrations through a typed **SQLite-backed API**.

Key characteristics:

- **Type-safe CRUD** operations on core entities
- **Migration system** in `runtime/state-store/src/migrations/` for schema evolution
- **Capability registry** for workspace-level feature enablement

Migrations follow a numbered file pattern (e.g., [`042-new-table.ts`](https://github.com/holaboss-ai/holaOS/blob/main/042-new-table.ts) or [`001-workspace-plugins.ts`](https://github.com/holaboss-ai/holaOS/blob/main/001-workspace-plugins.ts)) and guarantee backward compatibility during deployments.

### Harnesses Layer

**Harnesses** implement runtime-side capabilities as MCP-compatible tools. Located in `runtime/harnesses/src/`, they expose functionality like native web search, model routing, skill policies, and tool budgeting.

The MCP interface ([`runtime/harnesses/src/mcp.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/mcp.ts)) serves as the统一 entry point. Other components discover and invoke harness capabilities through this abstraction, decoupling consumers from implementation details.

Notable harness implementations:

- [`native-web-search.ts`](https://github.com/holaboss-ai/holaOS/blob/main/native-web-search.ts) — Direct web search without external API dependencies
- [`skill-policy.ts`](https://github.com/holaboss-ai/holaOS/blob/main/skill-policy.ts) — Capability enforcement and access control
- [`tool-replay-budget-ledger.ts`](https://github.com/holaboss-ai/holaOS/blob/main/tool-replay-budget-ledger.ts) — Cost tracking and rate limiting

### Channel Gateway Layer

External integrations enter hollaOS through the **channel gateway** ([`runtime/channel-gateway/src/manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/manager.ts)). It handles protocol-specific concerns—session key generation, message routing, and response formatting—before passing normalized payloads to the runtime.

Key files:

- [`manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/manager.ts) — Central coordination point
- [`ingress.ts`](https://github.com/holaboss-ai/holaOS/blob/main/ingress.ts) — Inbound message processing
- [`ports.ts`](https://github.com/holaboss-ai/holaOS/blob/main/ports.ts) — Protocol adapters (Telegram, Slack, etc.)
- [`session-key.ts`](https://github.com/holaboss-ai/holaOS/blob/main/session-key.ts) — Session identification
- [`format/telegram-html.ts`](https://github.com/holaboss-ai/holaOS/blob/main/format/telegram-html.ts) — Response formatting for specific channels

The gateway's design allows new communication channels by implementing additional ports without modifying core runtime logic.

### API Server Layer

The **API server** exposes HTTP endpoints for CRUD operations on sessions, capabilities, and resources. Built with Fastify-style handlers, it translates external requests into state store operations. Build configuration resides in [`runtime/api-server/tsup.config.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/tsup.config.ts).

This layer serves as the bridge between the desktop UI and the persistence layer, handling authentication, validation, and request routing.

### Desktop UI Layer

The **desktop UI** (`apps/desktop/`) is an Electron-like React application rendering workspace environments. It provides:

- **Workspace icon catalogs** via [`workspace-icon-catalog.tsx`](https://github.com/holaboss-ai/holaOS/blob/main/workspace-icon-catalog.tsx)
- **Markdown editing** through the editor package integration
- **Runtime interaction** via the runtime-client package

Mock implementations like [`apps/desktop/src/utils/mockAssistant.ts`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/src/utils/mockAssistant.ts) support development without full backend connectivity.

### Supporting Packages

Two shared packages enable cross-layer functionality:

| Package | Purpose | Entry Point |
|---------|---------|-------------|
| **runtime-client** | Typed HTTP client for UI-to-API communication | [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts) |
| **editor** | Markdown utilities and editing components | [`packages/editor/src/markdown.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/editor/src/markdown.ts) |
| **ui** | Shared theme components and utilities | [`packages/ui/src/lib/utils.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/ui/src/lib/utils.ts) |

## Data Flow Through the Architecture

Understanding how requests traverse hollaOS reveals the interaction patterns between layers.

### Inbound Message Flow

1. **External service** delivers message to the channel gateway
2. **Gateway** creates session key ([`session-key.ts`](https://github.com/holaboss-ai/holaOS/blob/main/session-key.ts)) and normalizes payload
3. **Harness selection** — Gateway invokes appropriate harness via MCP interface
4. **State consultation** — Harness queries store for workspace capabilities and budget status
5. **Execution** — Harness performs operation (model routing, web search, etc.)
6. **Persistence** — Results written to state store with migration-safe schema
7. **Response formatting** — Harness returns output to gateway for channel-specific formatting

### UI Action Flow

1. **Desktop component** triggers action (e.g., capability edit)
2. **Runtime client** ([`request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/request.ts)) constructs typed HTTP request
3. **API server** receives, validates, and routes request
4. **State store** executes CRUD operation with migration handling
5. **Response** propagates back through chain to update UI state

## Extensibility Patterns

The modular architecture supports extension at defined boundaries.

### Adding a New Harness

1. Create TypeScript implementation in `runtime/harnesses/src/`
2. Register in [`harness-mcp.ts`](https://github.com/holaboss-ai/holaOS/blob/main/harness-mcp.ts) with tool metadata
3. Expose via `MCP.runTool()` interface

### Adding a New Channel

1. Implement port adapter in [`channel-gateway/src/ports.ts`](https://github.com/holaboss-ai/holaOS/blob/main/channel-gateway/src/ports.ts)
2. Add routing rule in [`manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/manager.ts)
3. Create formatter in `format/` directory if needed

### Adding a Database Migration

1. Number migration sequentially (e.g., [`043-custom-capability.ts`](https://github.com/holaboss-ai/holaOS/blob/main/043-custom-capability.ts))
2. Place in `runtime/state-store/src/migrations/`
3. Implement up/down methods following existing patterns

## Code Examples

### Storing a Capability

```typescript
import { Store } from '@/runtime/state-store/src/store';

await Store.capabilities.add({
  workspaceId: 'ws_123',
  capability: {
    type: 'tool',
    name: 'web-search',
    config: { budget: 1000 },
  },
});

```

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

### Invoking MCP Tool

```typescript
import { MCP } from '@/runtime/harnesses/src/mcp';

const results = await MCP.runTool('nativeWebSearch', {
  query: 'latest TypeScript features',
});

```

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

### Gateway Message Handling

```typescript
import { ChannelGateway } from '@/runtime/channel-gateway/src/manager';

await ChannelGateway.handleIncoming({
  channel: 'telegram',
  payload: { text: 'Hello, holla OS!' },
});

```

*Source: [`runtime/channel-gateway/src/manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/manager.ts)*

### UI API Request

```typescript
import { request } from '@holaOS/runtime-client';

const sessions = await request.get('/api/sessions');

```

*Source: [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts)*

## Critical Implementation Files

| File | Responsibility |
|------|--------------|
| [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts) | Typed persistence API |
| [`runtime/harnesses/src/mcp.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/mcp.ts) | Capability exposure interface |
| [`runtime/channel-gateway/src/manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/manager.ts) | External service bridge |
| [`apps/desktop/src/components/ui/workspace-icon-catalog.tsx`](https://github.com/holaboss-ai/holaOS/blob/main/apps/desktop/src/components/ui/workspace-icon-catalog.tsx) | UI icon registry |
| [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts) | Frontend HTTP client |
| [`runtime/harnesses/src/native-web-search.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/harnesses/src/native-web-search.ts) | Standalone search tool |
| [`runtime/state-store/src/migrations/001-workspace-plugins.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/migrations/001-workspace-plugins.ts) | Schema evolution example |

## Summary

- **hollaOS architecture** separates concerns into state store, harnesses, channel gateway, API server, and desktop UI layers
- **MCP interface** ([`mcp.ts`](https://github.com/holaboss-ai/holaOS/blob/main/mcp.ts)) provides the primary integration point for runtime capabilities
- **State store migrations** enable zero-downtime schema evolution through numbered TypeScript files
- **Channel gateway** abstracts external protocols, allowing new integrations via port implementations
- **TypeScript-first design** ensures end-to-end type safety from database through UI components

## Frequently Asked Questions

### What database does hollaOS use for persistence?

hollaOS uses **SQLite** as its backing store, accessed through a typed TypeScript API in [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts). The file-based nature suits desktop and single-tenant deployments while migrations in `runtime/state-store/src/migrations/` handle schema evolution.

### How do harnesses differ from plugins in hollaOS?

**Harnesses** are runtime-side capability implementations that expose tools through the **MCP (Model-Controlled Plugin)** interface. They execute within the hollaOS runtime with direct state store access. Plugins, referenced in migration files like [`001-workspace-plugins.ts`](https://github.com/holaboss-ai/holaOS/blob/main/001-workspace-plugins.ts), appear to represent workspace-level capability registrations rather than runtime implementations.

### Can hollaOS integrate with channels beyond Telegram?

Yes—the **channel gateway** architecture in [`runtime/channel-gateway/src/ports.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/channel-gateway/src/ports.ts) is designed for extensibility. Each channel implements a port adapter, and routing logic in [`manager.ts`](https://github.com/holaboss-ai/holaOS/blob/main/manager.ts) dispatches to the appropriate handler. The `format/` directory contains channel-specific response formatters.

### What is the role of the runtime-client package?

The **runtime-client** package ([`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts)) provides the typed HTTP client that frontend code uses to call the API server. It encapsulates request construction, error handling, and response parsing—ensuring type safety across the network boundary.