# Core Principles of Maka's Architecture: How Apache Maka Orchestrates Multi-Agent Systems

> Explore the core principles of Apache Maka's architecture: modularity, separation of concerns, event sourcing, privacy, and more. Learn how Maka orchestrates multi-agent systems effectively.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-09-04

---

**Apache Maka is built on eight immutable design principles—modular plugin-driven runtime, strict separation of concerns between host/runtime/agent, event-sourced state machines, privacy-first data workspaces, declarative capability registries, deterministic scheduling, composable runtime phases, and language-agnostic JSON APIs—that collectively enable extensible, auditable, and privacy-preserving multi-agent workflows.**

Apache Maka is an open-source framework designed to orchestrate complex multi-agent workflows through a carefully architected runtime environment. Understanding the core principles of Maka's architecture is essential for developers extending the platform or integrating custom LLM providers. These principles are documented throughout the repository in files like [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) and the `docs/architecture/` directory, governing everything from plugin registration to state persistence.

## The Eight Core Architectural Principles

The following principles shape every component of the Apache Maka system, from the sandboxed host environment to the LLM-driven agent logic.

### Modular, Plugin-Driven Runtime

The core runtime loads capabilities—tools, agents, and storage back-ends—as independent plugins. Each plugin implements a well-defined interface, allowing new functionality to be added without modifying the core engine. According to [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), this design ensures that the runtime remains lean while supporting extensible functionality through the **Capability Registry**.

### Separation of Concerns: Host, Runtime, and Agent

As detailed in [`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md), Maka enforces a strict three-layer separation:

- **Host**: Provides the execution sandbox (container, OS, network)
- **Runtime**: Coordinates the flow of messages, state, and event logs
- **Agent**: Contains the LLM-driven logic that decides what to do next

This separation ensures that infrastructure concerns remain isolated from business logic, enabling the same agent code to run in different sandbox environments.

### Event-Sourced State Machine

All state changes are persisted as immutable events. The current view of a session is reconstructed by replaying those events, guaranteeing reproducibility and auditability. The [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md) file specifies that this pattern is implemented through the `RuntimeEventStore` and `RuntimeReadModel` classes.

### Privacy-First Data Model

User data is compartmentalized into **workspaces** with explicit access controls. As documented in [`docs/workspace-privacy-context.md`](https://github.com/apache/maka/blob/main/docs/workspace-privacy-context.md), the system enforces privacy boundaries at the data layer rather than just the UI layer, ensuring sensitive information remains isolated within workspace sandboxes.

### Declarative Capability Registry

Capabilities are declared in a manifest ([`capability.yaml`](https://github.com/apache/maka/blob/main/capability.yaml)) that the runtime reads at start-up. This enables automatic discovery, versioning, and validation of plugins. The [`docs/archive/maka-capability-audit-v1-2026-05.md`](https://github.com/apache/maka/blob/main/docs/archive/maka-capability-audit-v1-2026-05.md) file describes how the `CapabilityRegistry` validates these manifests against the runtime's security and compatibility requirements.

### Deterministic Scheduling

The scheduler assigns work to agents based on a deterministic priority queue, ensuring repeatable execution order across runs. According to [`docs/blogs/multi-agent-scheduling.md`](https://github.com/apache/maka/blob/main/docs/blogs/multi-agent-scheduling.md), this principle prevents race conditions in multi-agent workflows and guarantees that identical inputs produce identical execution sequences.

### Composable Runtime Phases

The runtime is split into distinct **phases** (ingestion, planning, execution, post-processing). Each phase can be swapped or extended, allowing experimentation without breaking the entire pipeline. The [`docs/work-board-phase1.md`](https://github.com/apache/maka/blob/main/docs/work-board-phase1.md) documentation explains how these phases communicate through well-defined interfaces.

### Open, Language-Agnostic APIs

Communication between host, runtime, and agents happens over JSON-based messages. As noted in [`docs/cli-distribution.md`](https://github.com/apache/maka/blob/main/docs/cli-distribution.md), this design makes it easy to replace the LLM backend (OpenAI, Anthropic, Azure, etc.) without code changes, since the protocol is strictly decoupled from implementation languages.

## Implementation Patterns in the Apache Maka Source Code

These architectural principles manifest in specific code patterns throughout the `apache/maka` repository. Below are minimal snippets illustrating how developers interact with these core concepts.

### Initializing the Runtime Host

The `RuntimeHost` class in `@maka/runtime-host` abstracts the OS/container boundary, keeping the runtime completely sandboxed:

```typescript
import { RuntimeHost } from '@maka/runtime-host';

// Create a host that runs inside a Docker container (the default sandbox)
const host = new RuntimeHost({
  containerImage: 'apache/maka-runtime:latest',
  env: { MAKAPORT: '8080' },
});

// Initialise the host – this spins up the sandbox and loads all registered capabilities
await host.start();

```

### Registering Capabilities via the Registry

Plugins integrate through the `CapabilityRegistry` using declarative manifests that specify permissions and schemas:

```typescript
import { CapabilityRegistry } from '@maka/capability-registry';
import { MyTool } from './my-tool';

CapabilityRegistry.register({
  name: 'my-tool',
  version: '1.0.0',
  implementation: MyTool,
  // Declare required permissions and the data schema it consumes/produces
  permissions: ['read:workspace', 'write:log'],
});

```

### Executing Agent Sessions

Agents interact with the runtime only through the well-defined JSON message protocol, preserving language-agnosticism:

```typescript
import { AgentRun } from '@maka/agent-run';
import { OpenAIProvider } from '@maka/providers/openai';

const run = new AgentRun({
  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
  workspaceId: 'ws-1234',
});

await run.execute();   // Orchestrates ingestion → planning → execution phases

```

### Reconstructing State from Events

The event-sourced architecture guarantees that session state can be fully reconstructed at any point by replaying events:

```typescript
import { RuntimeEventStore } from '@maka/event-store';

// Pull all events for a given session
const events = await RuntimeEventStore.readRuntimeEvents({ sessionId: 'sess-5678' });

// Build the current view by replaying the events
const sessionView = RuntimeReadModel.applyEvents(events);
console.log(sessionView);

```

## Key Architectural Documentation Files

The following files in the Apache Maka repository capture the architectural vision, implementation details, and contracts that maintain system cohesion:

- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** — High-level description of all core principles and component interactions
- **[`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md)** — Details the host sandbox, lifecycle, and communication contracts
- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)** — Explains the event-sourced runtime core, phases, and scheduler
- **[`docs/workspace-privacy-context.md`](https://github.com/apache/maka/blob/main/docs/workspace-privacy-context.md)** — Defines the privacy model and workspace isolation mechanisms
- **[`packages/eval/README.md`](https://github.com/apache/maka/blob/main/packages/eval/README.md)** — Shows how the evaluation package validates architecture contracts and compliance
- **[`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md)** — Provides the CLI entry-point that ties together host, runtime, and agents

## Summary

- **Apache Maka** implements a plugin-driven architecture where capabilities are loaded dynamically via the `CapabilityRegistry`, allowing extension without core modifications.
- The system enforces strict **separation of concerns** between the Host (sandbox), Runtime (coordination), and Agent (LLM logic) layers.
- **Event sourcing** provides immutable audit trails and reproducible state through `RuntimeEventStore` and `RuntimeReadModel`.
- **Workspace-based privacy controls** enforce data isolation at the storage layer, not just the application layer.
- **Declarative manifests** ([`capability.yaml`](https://github.com/apache/maka/blob/main/capability.yaml)) enable automatic plugin discovery, versioning, and validation.
- **Deterministic scheduling** and **composable phases** ensure repeatable, modular workflow execution.
- **JSON-based APIs** decouple components, enabling language-agnostic integration and swappable LLM providers.

## Frequently Asked Questions

### How does Maka's plugin system work without modifying core code?

Maka uses the `CapabilityRegistry` class to load plugins dynamically at startup. Each plugin declares its interface, permissions, and version in a manifest file ([`capability.yaml`](https://github.com/apache/maka/blob/main/capability.yaml)), which the runtime validates and registers automatically. This allows developers to add tools, agents, or storage backends by simply placing files in the capabilities directory without touching the core engine source.

### What makes Maka's state management reproducible and auditable?

The system implements an **event-sourced state machine** where all state changes are stored as immutable events in the `RuntimeEventStore`. The current session view is computed by calling `RuntimeReadModel.applyEvents()` to replay the event sequence. Since the event log is append-only and immutable, any past state can be reconstructed exactly, providing complete auditability and debugging capabilities.

### How does Maka enforce privacy boundaries between different users or teams?

Maka implements a **privacy-first data model** that compartmentalizes data into isolated workspaces. As documented in [`docs/workspace-privacy-context.md`](https://github.com/apache/maka/blob/main/docs/workspace-privacy-context.md), access controls are enforced at the data layer, meaning the runtime validates workspace permissions before any data read or write operation. This ensures that agents and tools operating in one workspace cannot access data from another, regardless of UI configurations.

### Can I use Maka with LLM providers other than OpenAI?

Yes. The **language-agnostic API** principle ensures that all communication between components uses JSON messages. The `AgentRun` class accepts any provider implementing the standard interface, such as `OpenAIProvider`, `AnthropicProvider`, or `AzureProvider`. Because the protocol is decoupled from the implementation, switching LLM backends requires only configuration changes, not code modifications.