hollaOS Architecture: A Deep Dive into the Modular TypeScript Platform

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) 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 or 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) 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 — Direct web search without external API dependencies
• skill-policy.ts — Capability enforcement and access control
• 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). It handles protocol-specific concerns—session key generation, message routing, and response formatting—before passing normalized payloads to the runtime.

Key files:

• manager.ts — Central coordination point
• ingress.ts — Inbound message processing
• ports.ts — Protocol adapters (Telegram, Slack, etc.)
• session-key.ts — Session identification
• 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.

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
• Markdown editing through the editor package integration
• Runtime interaction via the runtime-client package

Mock implementations like 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
editor	Markdown utilities and editing components	packages/editor/src/markdown.ts
ui	Shared theme components and utilities	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) 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) 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 with tool metadata
3. Expose via MCP.runTool() interface

Adding a New Channel

1. Implement port adapter in channel-gateway/src/ports.ts
2. Add routing rule in manager.ts
3. Create formatter in format/ directory if needed

Adding a Database Migration

1. Number migration sequentially (e.g., 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

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

Invoking MCP Tool

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

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

Source: runtime/harnesses/src/mcp.ts

Gateway Message Handling

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

UI API Request

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

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

Source: packages/runtime-client/src/request.ts

Critical Implementation Files

File	Responsibility
runtime/state-store/src/store.ts	Typed persistence API
runtime/harnesses/src/mcp.ts	Capability exposure interface
runtime/channel-gateway/src/manager.ts	External service bridge
apps/desktop/src/components/ui/workspace-icon-catalog.tsx	UI icon registry
packages/runtime-client/src/request.ts	Frontend HTTP client
runtime/harnesses/src/native-web-search.ts	Standalone search tool
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) 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. 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, 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 is designed for extensibility. Each channel implements a port adapter, and routing logic in 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) 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.

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