Architecture

Pi-native OpenWaggle architecture: Electron shell, hexagonal main process, and SQLite session projection.

OpenWaggle is an Electron desktop app with a Pi-native runtime core.

Process Boundaries

src/
  main/              # Node.js process: ports, adapters, IPC, SQLite projection
  preload/           # Typed contextBridge API
  renderer/src/      # React 19 UI
  shared/            # Vendor-free types and schemas

The renderer has no direct Node access and no Pi SDK imports. It talks to the main process through typed IPC exposed by preload.

Hexagonal Main Process

Pi is confined to src/main/adapters/pi/.

Layer	Responsibility
`domain/`	Pure business logic. No infrastructure or vendor imports.
`ports/`	Effect service interfaces such as `AgentKernelService`, `ProviderService`, and session repositories.
`adapters/`	Concrete implementations, including Pi and SQLite adapters.
`application/`	Business orchestration through ports.
`ipc/`	Transport handlers, active-run tracking, and IPC event emission.
`store/`	SQLite persistence primitives behind adapters.

Runtime Flow

When a user sends a message:

The renderer invokes agent:send-message.
The IPC handler delegates run coordination to the application layer.
AgentKernelService resolves to the Pi adapter.
The Pi adapter creates project-scoped Pi services for the selected provider-qualified model.
Pi runs the session with its native tool surface.
The adapter translates Pi events into OpenWaggle-owned AgentTransportEvent values.
SQLite session projection tables persist sessions, nodes, branches, and branch UI state.

The renderer reads the session projection through OpenWaggle-owned IPC DTOs. Session Tree selection, branch rows, draft branch state, and route branch/node search parameters are UI over that projection rather than direct Pi SDK objects.

Provider And Model Metadata

Provider/model/auth data comes from Pi ModelRegistry and AuthStorage. OpenWaggle exposes that metadata through ports and IPC DTOs so the settings UI can curate enabled models.

Tool Surface

Pi owns tool execution. OpenWaggle renders Pi-emitted tool events directly in the transcript.

Project Resources

OpenWaggle injects project resource roots into Pi with .openwaggle > .pi > .agents precedence for skills, extensions, prompts, and themes. OpenWaggle-owned catalog toggles apply where the app owns the catalog surface; Pi-native discovery still governs Pi-owned/global resources.

Tech Stack

Layer	Technology
Framework	Electron 40 + electron-vite
Runtime	Pi SDK behind OpenWaggle ports/adapters
Main orchestration	Effect
UI	React 19, Zustand, Tailwind CSS v4
Storage	SQLite + `.openwaggle/settings.json` project config
Terminal	xterm.js + node-pty