00-orientation.md

Overview

The one-sentence architecture

PiNative is a native SwiftUI/AppKit shell that owns projects, navigation, presentation, and cached UI state while a separate pi --mode rpc subprocess owns agent execution, providers, tools, and canonical Pi session files.

SwiftUI shell → AppModel → one PiConversationModel per chat
                              ↓
                         PiRPCClient actor
                              ↓ JSONL over stdin/stdout
                         pi --mode rpc

Start with these five files

• PiNativeApp.swift — process entry point, window scene, app commands, and shutdown.
• MainWindowView.swift — three-region shell and modal routing.
• AppModel.swift — app-level source of truth and runtime registry.
• PiConversationModel.swift — one chat's lifecycle, transcript, composer, and Pi event interpretation.
• PiRPCClient.swift — subprocess and JSON-RPC transport boundary.

Ownership rule

• AppModel answers which project/chat/surface is active?
• PiConversationModel answers what is happening in this chat?
• PiRPCClient answers how do commands and events cross the process boundary?
• Views render observable state and keep only ephemeral presentation state locally.