Mobile Architecture

A route becomes a screen through a pure decision layer and a thin DOM layer, and a completed turn is joined to persistence at one named seam. Two enforced seams — one for the agent framework, one for the UI shell — keep engines and shells swappable.

import { enginesFor } from "praisonai-mobile/app/registry";

const engines = enginesFor({ settings, http });

Quick Start

The composition root builds everything concrete

createApp takes its adapters injected, so the whole boot runs under test against fakes.

const booted = await createApp({
  storage: platform.storage,
  secrets: platform.secrets,
  time: platform.time,
  shell: platform.shell,
  // A FACTORY, not an array: the engine list is built FROM the session.
  engines: (persistence) => enginesFor({ settings: facadeStub(), http: platform.http, persistence }),
  settingDefs: SETTING_DEFS,
  engineId: "remote-http",
  onPublish: publish,
  now: () => Date.now(),
  newChatId: () => globalThis.crypto.randomUUID(),
});

The session is bridged to the engine with persistenceFor

boot.ts builds the session first, then hands it to the engine factory through the named adapter persistenceFor.

const session = createSession({ storage, engineId, now, newChatId });
const selection = await selectEngine(engineId, deps.engines(persistenceFor(session)));

Decide what changes (pure)

screenFor(route) maps a route to a ScreenId, and transition(from, to, live) returns a ScreenChange describing what to mount, hide, and remove. No DOM is touched here, so the decision is tested without a browser.

Apply it to the page (thin)

createScreens(host).apply(change) mounts, hides, and removes nodes according to the ScreenChange. It mounts the next screen before hiding the current one, so there is never a blank frame.

Read the layer graph

cat tools/boundaries.json

The graph is data, not convention.

Check the boundaries

npm run boundaries

tools/depgraph.mjs reports every import that crosses a line it should not.

Boot Order

The boot sequence runs in one order, and that order exists because the in-process engine writes through the session.

Step	What happens	Why here
1. Load settings	`createSettingsStore(...).load()`	The engine choice and credentials come from settings; building first means rebuilding.
2. Create session	`createSession(...)`	The in-process engine writes through it, so it must exist first.
3. Bridge	`persistenceFor(session)`	Adapts `Session.record(prompt, answer)` to `RunPersistence.record(request, answer)`.
4. Build engines	`deps.engines(persistenceFor(session))`	The factory receives the thing engines write through.
5. Select engine	`selectEngine(engineId, choices)`	A protocol mismatch stops the boot here, with a name, not mid-answer.
6. Controller	`createRunController({ engine, ... })`	Everything above the seam, none of it naming a concrete adapter.

The Route→Screen Seam

Navigation splits into a pure half and a thin half so the part worth testing has no DOM in it.

Layer	File	Responsibility
Decision (pure)	`ui/src/screens.ts`	`screenFor`, `transition`, `RETAINED` — returns a description of what should change
DOM (thin)	`app/src/mount.ts`	Appends, hides, and removes nodes per the description

A ScreenChange carries the plan: show, mount, unmount, hide, and noop. A retained screen appears in hide, never unmount — its nodes stay so scroll position and streaming survive.

A chat-to-chat move is a content change, not a screen change — transition returns noop: true so the transcript is not rebuilt on navigation within the same screen.

The Persistence Seam

The engine writes a completed turn through the same session the UI reads, joined at one named adapter. persistenceFor(session) in core/src/chat/session.ts is the one place the engine’s RunPersistence vocabulary and the Session vocabulary meet. The engine calls record(request, answer); the adapter forwards request.prompt to session.record(prompt, answer). Naming the adapter — rather than inlining a lambda at the call site — keeps this seam findable. The wiring is enforced by the type: AppDeps.engines is a factory (persistence) => EngineChoice[], built from the session. There is no way to obtain the engine list without being handed the store engines write through.

end.userIndex === null means the turn was not written to disk — the write failed, so the UI withholds Fork and Delete. Index 0 is valid, so a falsy check is a trap.

Streaming Pacing

Tokens flow through a coalescer that flushes either when it has enough bytes or after a short delay, so short answers still paint incrementally. The coalescer paints on whichever bound is hit first.

Bound	Default	Meaning
`maxBytes`	`256`	Flush once this many buffered characters accumulate.
`maxDelayMs`	`16`	Flush this long after the first buffered byte, however few arrived.

If the periodic tick is not wired, only the byte cap can flush — so a 130-character answer produces zero intermediate paints and arrives in one lump when the run ends. The delay bound is what makes a short answer stream at all; that is why the pacing design matters, not merely how fast it is.

How It Works

Each layer declares what it may import. app sits at the top and wires everything; protocol sits at the bottom and imports nothing.

Layer	May import	Purpose
`protocol`	—	The wire contract and the 11 events.
`core`	`protocol`	Ports, run controller, transcript, chat, settings.
`engines`	`protocol`, `core`	Agent-framework implementations.
`adapters`	`protocol`, `core`	UI-shell implementations.
`ui`	`protocol`, `core`	Framework-free render logic.
`app`	all of the above	The composition root.

Why a Factory, Not an Array

AppDeps.engines is a factory whose type refuses a pre-built list.

readonly engines: (persistence: RunPersistence) => readonly EngineChoice[];

A pre-built array was the original bug: the session existed, the engine’s persistence port existed, and nothing connected them — so record() never ran in a real turn and no conversation was ever saved. Taking a factory makes that impossible to express: there is no way to obtain the engine list without being handed the thing engines write through. The wiring is enforced by the type, not by a comment.

persistenceFor(session) is a named adapter in core/src/chat/session.ts, not an inline lambda. It is the one place the two vocabularies meet — Session.record(prompt, answer) versus RunPersistence.record(request, answer) — and a lambda buried in composition is a seam nobody can find later.

Why Build-Enforced

A rule enforced only by review stops being enforced. tools/depgraph.mjs runs in CI (.github/workflows/mobile.yml) and fails the build on any crossing.

"externals": {
  "praisonai": ["engines/src/praisonai-ts"],
  "@tauri-apps/api": ["adapters/src/tauri/bridge.ts"],
  "@tauri-apps/plugin-*": ["adapters/src/tauri"]
}

Only engines/src/praisonai-ts may import praisonai. Only adapters/src/tauri may import @tauri-apps/*. Everything above the seams is written against ports and cannot tell one implementation from another.

Choose Your Extension Point

Which directory you touch depends on what you are adding.

Common Patterns

Boot fails loud when an engine cannot hold the contract.

if (!booted.ok) {
  renderFatal(root, strings.bootFailed(booted.detail));
  return null;
}

Teardown runs in reverse and is idempotent.

async dispose() {
  if (disposed) return;
  disposed = true;
  for (const off of subscriptions.splice(0)) off();
  await controller.stop();
  await engine.dispose();
}

Best Practices

Build the session before the engine list

The in-process engine writes through the session, so a pre-built engine list cannot carry a live persistence. Always call createSession first, then deps.engines(persistenceFor(session)).

Name the bridge, do not inline it

persistenceFor is exported by name. Inlining the adapter as a lambda at the call site hides the one seam where the session and the engine vocabularies meet.

Keep the composition root injectable

createApp takes every adapter as a parameter. A composition root that constructs its own dependencies is the one part of an app that can never be tested — and it is where ordering bugs live.

Keep decisions out of the DOM layer

Anything that decides what to keep or destroy belongs in screens.ts as a pure function. mount.ts only carries out the plan, so a test can inspect the plan without a browser.

Mount before hide

Always mount the next screen before hiding the current one. The reverse order shows a blank page for one frame on every navigation.

Trust the persisted index, not the screen

A cancelled or errored turn stays on screen but is never written, so screen position and disk position diverge. Read the index the writer reports in end, and treat null as “not on disk”.

Add, never reach across

A new framework is a directory under engines/src plus a conformance run — never an edit above the seam.

Keep ui/ framework-free

ui/ returns descriptions of what to render, so a React Native port reimplements only the renderer and reuses everything else.

Let CI hold the line

Run npm run boundaries locally; the same gate runs on every push and PR.

Test pacing against a fake clock that ticks

A TimePort.every fake that returns () => () => {} is worse than no test — it never fires the tick, so every test using it passes for the wrong reason. Pacing must be driven by a fake clock that actually advances, or a coalescer whose delay bound was never wired looks correct in green.

Overview

Retained chat and native navigation.

Engines

Which engine owns the write, and why only one does.

Shell & Adapters

The keyboard snapshot and the pinch-zoom guard.

Capabilities & Gaps

What each engine can and cannot report.

Native Shell

The Tauri shell — safe-area, keyboard, lifecycle, and back-gesture arbitration.

Shell & Adapters

The UI-shell seam in detail.

Protocol

The 11 events every engine speaks.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Mobile Architecture

Quick Start

Boot Order

The Route→Screen Seam

The Persistence Seam

Streaming Pacing

How It Works

Why a Factory, Not an Array

Why Build-Enforced

Choose Your Extension Point

Common Patterns

Best Practices

Overview

Engines

Shell & Adapters

Capabilities & Gaps

Native Shell

Shell & Adapters

Protocol

​Quick Start

​Boot Order

​The Route→Screen Seam

​The Persistence Seam

​Streaming Pacing

​How It Works

​Why a Factory, Not an Array

​Why Build-Enforced

​Choose Your Extension Point

​Common Patterns

​Best Practices

​Related

Overview

Engines

Shell & Adapters

Capabilities & Gaps

Native Shell

Shell & Adapters

Protocol

Quick Start

Boot Order

The Route→Screen Seam

The Persistence Seam

Streaming Pacing

How It Works

Why a Factory, Not an Array

Why Build-Enforced

Choose Your Extension Point

Common Patterns

Best Practices

Related