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

The authoritative Maka backend architecture documentation is located in the 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 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 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 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 lines 77-85 (the "Reading paths" section), these files provide detailed designs for:

• docs/architecture/runtime-host-architecture.md – Detailed Runtime Host design and lifecycle management
• docs/architecture/peer-mesh-architecture.md – Peer mesh networking and membership protocols
• 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 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. This class creates and manages sessions for each connecting client:

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. This class handles the generation of cells and result selection:

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 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 implements the Runtime Host session management described in the architecture docs.
• 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 lines 65-76.

Frequently Asked Questions

Where is the main Maka backend architecture documentation located?

The primary documentation is in 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, 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, 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.

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