# Where to Find Maka Backend Architecture Documentation: Complete Guide to ARCHITECTURE.md and Source Code

> Locate Maka backend architecture documentation easily. Find the ARCHITECTURE.md file and explore deep dives in the source code for a complete guide.

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

---

**The authoritative Maka backend architecture documentation is located in the [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) file at the repository root, with supplementary deep dives in the `docs/architecture/` folder.**

The Apache Maka project maintains comprehensive backend architecture documentation that defines how State Root Runtime Hosts, evaluation boundaries, and core packages interact. This guide maps exactly where to find the Maka backend architecture documentation and how the described concepts translate into the actual source code implementation.

## Primary Documentation in ARCHITECTURE.md

The main entry point for understanding Maka's backend design is [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) in the repository root. According to the Apache Maka source code, this document delineates the overall design, runtime layers, evaluation boundaries, and code-level responsibilities.

### High-Level System Overview

Lines 22-33 of [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) explain that **each State Root has its own Runtime Host**, and detail how Desktop, TUI, CLI, bots, and evaluation clients interact with that host. This section establishes the fundamental topology: every unique state root operates within its dedicated runtime environment, with multiple client types connecting to a single host instance.

### Runtime Layers and Components

The documentation at lines 44-48 breaks down the **Event Log**, **SessionManager/AgentRun**, **Agent Graph**, and **Storage** responsibilities. These layers form the execution stack where events are logged, sessions are managed, agent graphs are executed, and state is persisted.

### Eval Boundary Specifications

Lines 50-59 define the **evaluation boundary** concepts, including experiments, cells, repetitions, and continuations. This boundary separates the experiment orchestration logic from the runtime execution, ensuring reproducible evaluation semantics.

### Code Boundaries and Package Mapping

At lines 65-76, [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) maps high-level responsibilities to concrete packages:

- **`packages/core`** – Session definitions, Runtime Events, AgentRun, and protocol contracts
- **`packages/runtime-host`** – Hosted execution authority and client protocols
- **`packages/eval`** – Experiment cells, attempts, and result selection logic

## Deep Dive Architecture Documentation

Beyond the main overview, the `docs/architecture/` folder contains specialized documentation for specific subsystems. As referenced in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) lines 77-85 (the "Reading paths" section), these files provide detailed designs for:

- **[`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md)** – Detailed Runtime Host design and lifecycle management
- **[`docs/architecture/peer-mesh-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/peer-mesh-architecture.md)** – Peer mesh networking and membership protocols
- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)** – Core runtime event log and projection mechanisms
- **Agent Graph and compaction designs** – Specific implementations for graph execution and state compaction

## Code-Level Architecture Implementation

The architectural concepts documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) directly correspond to specific TypeScript implementations in the `packages/` directory.

### Runtime Host Session Management

The **Runtime Host** owns the session lifecycle, as implemented in [`packages/runtime-host/src/host.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/host.ts). This class creates and manages sessions for each connecting client:

```typescript
import { SessionManager } from "@maka/runtime";
import { RuntimeKernel } from "@maka/runtime-core";

export class RuntimeHost {
  private sessionMgr = new SessionManager();
  private kernel = new RuntimeKernel();

  // Host creates a new session for each client (desktop, CLI, bot, etc.)
  async createSession(clientId: string) {
    const session = await this.sessionMgr.startSession(clientId);
    return this.kernel.attach(session);
  }
}

```

This implementation mirrors the architecture documentation's description of how the host mediates between client connections and the runtime kernel.

### Eval Boundary Experiment Logic

The **Eval package** enforces experiment semantics through the `Experiment` class in [`packages/eval/src/experiment.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/experiment.ts). This class handles the generation of cells and result selection:

```typescript
import { Cell, Attempt } from "./types";

export class Experiment {
  // The specification (benchmark, executor, subjects, tasks, repetitions)
  constructor(public spec: ExperimentSpec) {}

  // Generates cells = task × repetition × subject
  generateCells(): Cell[] {
    // ...implementation...
  }

  // Determines the authoritative attempt for a cell
  selectResult(attempts: Attempt[]): Attempt | undefined {
    // earliest valid attempt wins (see ARCHITECTURE.md §63)
    // ...implementation...
  }
}

```

The `selectResult` method implements the specific logic referenced in section 63 of the architecture documentation, selecting the earliest valid attempt as the authoritative result.

## Key Backend Packages and Responsibilities

The Maka backend architecture documentation identifies these critical packages and their distinct responsibilities:

- **`packages/core`** – Defines fundamental types including Session, Runtime Event, AgentRun, permissions, and protocol contracts that cross package boundaries.

- **`packages/runtime-host`** – Implements the hosted execution authority described in the architecture docs, managing the public client protocol and session orchestration.

- **`packages/eval`** – Contains the experiment evaluation logic, including subject/executor adapters, cell generation, and the attempt selection algorithms that determine benchmark results.

## Summary

- The primary **Maka backend architecture documentation** resides in **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** at the repository root, covering system overview, runtime layers, and code boundaries.
- Deep-dive documentation for specific subsystems exists in the **`docs/architecture/`** folder, including detailed designs for the Runtime Host, Peer Mesh, and Runtime Core.
- **[`packages/runtime-host/src/host.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/host.ts)** implements the Runtime Host session management described in the architecture docs.
- **[`packages/eval/src/experiment.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/experiment.ts)** provides the Eval boundary implementation with experiment orchestration and result selection logic.
- The **`packages/core`**, **`packages/runtime-host`**, and **`packages/eval`** directories contain the concrete implementations mapped in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) lines 65-76.

## Frequently Asked Questions

### Where is the main Maka backend architecture documentation located?

The primary documentation is in **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** at the repository root. This file contains the comprehensive backend architecture overview, including the high-level design (lines 22-33), runtime layers (lines 44-48), and package boundaries (lines 65-76). Additional detailed documentation resides in the `docs/architecture/` folder.

### What are the core runtime layers documented in ARCHITECTURE.md?

According to lines 44-48 of the architecture documentation, the core runtime layers include the **Event Log** for immutable operation history, **SessionManager/AgentRun** for session lifecycle and execution context, **Agent Graph** for computational workflows, and **Storage** for state persistence. These layers form the vertical stack of the Runtime Host.

### How does the Eval boundary define experiments and result selection?

The Eval boundary, defined in lines 50-59, structures experiments as collections of **cells** (task × repetition × subject combinations) and **attempts** (individual execution runs). Result selection follows the logic implemented in [`packages/eval/src/experiment.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/experiment.ts), where the `selectResult` method chooses the earliest valid attempt as the authoritative result for each cell, as specified in section 63 of the architecture documentation.

### Which packages implement the Runtime Host and session management?

The **Runtime Host** implementation is located in **`packages/runtime-host`**, specifically in [`src/host.ts`](https://github.com/apache/maka/blob/main/src/host.ts), which manages session creation through the `SessionManager` and kernel attachment. The **session definitions and protocol contracts** are defined in **`packages/core`**, while the **experiment evaluation** that runs within these sessions is implemented in **`packages/eval`**.