# How the Apache Maka Desktop Session Projection System Works: A Technical Deep Dive

> Explore the technical details of Apache Maka's desktop session projection system. Learn how it combines logs and streaming data for efficient UI updates without full replay.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-25

---

**Apache Maka's desktop session projection system merges persisted SQLite transcript logs with real-time streaming data through memoized projection objects to deliver incremental, high-performance UI updates without full replay.**

The desktop session projection system in Apache Maka separates durable session history from transient live output to enable efficient rendering of AI-assisted workflows. This architecture, implemented in the `apache/maka` repository, ensures that the React-based UI displays a consistent, incrementally updated view of conversation state even as tool calls and model tokens stream in real time.

## Core Architecture: TranscriptProjection vs. LiveTurnProjection

The projection layer consists of two complementary abstractions that isolate stable history from volatile in-flight data.

### TranscriptProjection (Persistent Layer)

`TranscriptProjection` reads the durable transcript stored in `runtime.sqlite` and merges any live updates that arrive while a turn is still executing. According to the source code in [`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts), the `createTranscriptProjection()` factory returns a memoized object that **increments** over the event log rather than replaying the entire history on every render. This keeps updates at **O(1)** complexity per new event, reading only the tail of the log.

### LiveTurnProjection (Transient Layer)

`LiveTurnProjection` holds the ephemeral state of the current turn before it commits to the transcript. As implemented in [`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts), this projection captures pending tool events, streaming model tokens, and steering messages through the `applyLiveTurnEvent()` function. Once the turn reaches `terminal:true`, the live overlay freezes and merges into the persisted transcript, ensuring deterministic snapshots.

## Data Flow from Runtime to Renderer

The desktop session projection system processes events through a five-stage pipeline:

1. **Runtime Host → SessionManager** – The host executes a turn and writes discrete events to `runtime.sqlite`.
2. **SessionManager** – Exposes the event log via an observable API that the UI layer subscribes to.
3. **Projection Layer** – `createTranscriptProjection()` instantiates a memoized projection, while `applyLiveTurnEvent()` updates the transient `LiveTurnProjection` as streaming data arrives.
4. **React Hook** – Components call `useTranscriptProjection()` (defined in [`packages/ui/src/use-transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/use-transcript-projection.ts)), which returns `projection.project(input)` containing both `messages` (stable history) and `live` (transient overlay).
5. **Renderer** – Components consume the composite projection object. Because the projection returns the *same reference* when unchanged, React skips unnecessary re-renders.

## Key Implementation Files

The Apache Maka repository contains the desktop session projection system across these critical paths:

- **[`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts)** – Implements `createTranscriptProjection` and the incremental `project` method for durable transcript merging.
- **[`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts)** – Provides `applyLiveTurnEvent` and utilities for handling steering messages and pending tool output.
- **[`packages/ui/src/use-transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/use-transcript-projection.ts)** – React hook that wraps the projection in a stable reference for UI consumption.
- **[`packages/ui/src/materialize.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/materialize.ts)** – Consumes projection outputs to construct renderable UI structures.
- **[`packages/ui/src/__tests__/transcript-projection.test.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/__tests__/transcript-projection.test.ts)** – Validates the correctness of the incremental projection algorithm.

## React Integration Example

You can consume the projection system in your components through the provided hook. The following implementation demonstrates memoization and live overlay rendering:

```tsx
// packages/ui/src/use-transcript-projection.ts
import { createTranscriptProjection } from './transcript-projection.js';
import type { TranscriptProjectionInput } from './transcript-projection.js';
import { useRef } from 'react';

/**
 * Returns a stable projection for the given session input.
 */
export function useTranscriptProjection(input: TranscriptProjectionInput) {
  const projection = useRef<TranscriptProjection>(undefined);
  projection.current ??= createTranscriptProjection();
  return projection.current.project(input);
}

```

In a chat component, you render both the stable transcript and the live overlay:

```tsx
// Example component consuming the projection
import { useTranscriptProjection } from '@maka/ui';
import type { SessionId } from '@maka/core';

export function ChatWindow({ sessionId }: { sessionId: SessionId }) {
  const projection = useTranscriptProjection({ sessionId });

  return (
    <div>
      {projection.messages.map((msg) => (
        <Message key={msg.id} data={msg} />
      ))}

      {/* Live overlay shows incomplete tool output or streaming text */}
      {projection.live && <LiveOverlay data={projection.live} />}
    </div>
  );
}

```

In this pattern, `useTranscriptProjection` creates the memoized instance once per component, while `projection.project(input)` incrementally merges new events during each render cycle.

## Design Guarantees and Performance

The desktop session projection system enforces three critical guarantees:

- **Incremental Updates** – The first projection walk loads the full log; subsequent updates read only new events, maintaining O(1) performance per update.
- **Deterministic Snapshots** – Once a turn signals `terminal:true`, the system freezes the live overlay and atomically merges it into the persisted transcript, preventing race conditions.
- **Isolation** – The UI layer never accesses the raw SQLite file directly. All data flows through the projection layer, keeping renderers pure and enabling comprehensive unit testing.

## Summary

- Apache Maka uses a **dual-layer projection architecture** separating `TranscriptProjection` (persistent) from `LiveTurnProjection` (transient).
- The **`createTranscriptProjection()`** factory in [`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts) provides memoized, incremental reads of the SQLite event log.
- **Live updates** flow through `applyLiveTurnEvent()` in [`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts) until the turn reaches terminal state.
- The **`useTranscriptProjection`** hook exposes a stable reference that returns identical objects when unchanged, optimizing React render performance.
- The system guarantees O(1) incremental updates, deterministic freezing of live data, and complete isolation between storage and rendering layers.

## Frequently Asked Questions

### What is the difference between TranscriptProjection and LiveTurnProjection?

`TranscriptProjection` manages the durable history stored in `runtime.sqlite`, merging committed turns with any partial updates currently arriving. `LiveTurnProjection` exclusively holds the transient state of the active turn—including streaming tokens and pending tool calls—before that data commits to the permanent transcript. Once the turn completes, its live state freezes and integrates into the transcript projection.

### How does Apache Maka prevent unnecessary React re-renders when streaming data?

The projection system returns the **same object reference** when no new events have occurred, allowing React's equality checks to skip re-renders automatically. The `useTranscriptProjection` hook maintains a stable projection instance via `useRef`, and the underlying `project()` method only creates new objects when the input state actually changes, ensuring efficient updates even during high-frequency streaming.

### Where is the desktop session projection logic implemented in the repository?

The core logic resides in [`packages/ui/src/transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/transcript-projection.ts) for persistent transcript handling and [`packages/ui/src/live-turn-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/live-turn-projection.ts) for transient turn state. The React integration layer lives in [`packages/ui/src/use-transcript-projection.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/use-transcript-projection.ts), while [`packages/ui/src/materialize.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/materialize.ts) handles the transformation of projections into renderable UI components.

### How does the system ensure data consistency between the SQLite log and the UI?

All data access flows through the projection layer rather than direct SQLite queries. The `createTranscriptProjection()` function maintains internal pointers to the last processed event, incrementally consuming only new log entries. When a turn marks `terminal:true`, the projection atomically merges the live overlay into the stable transcript, ensuring the UI never displays orphaned or inconsistent intermediate states.