Architecture Overview

Rowboat is an Electron desktop application built as a nested pnpm monorepo. The architecture separates concerns across three Electron processes (main, renderer, preload) and shared business logic packages.

Architecture Diagram

Rowboat Desktop App
├── Main Process (Node.js)
│   ├── IPC Handlers
│   ├── Background Services
│   └── Core Business Logic
├── Renderer Process (Browser)
│   ├── React UI (Vite)
│   └── Sandboxed Environment
└── Preload Scripts
    └── Secure IPC Bridge

Electron Process Architecture

Main Process - Node.js Backend

The main process (apps/main/src/main.ts) is the Node.js backend that:

Creates and manages browser windows
Handles all file system and OS operations
Runs background services (Gmail sync, calendar sync, knowledge graph processing)
Exposes IPC handlers for renderer communication
Manages OAuth flows and external integrations

Key Characteristics:

Full Node.js access (fs, path, crypto, etc.)
Bundled with esbuild to single CommonJS file
No hot-reload in development (requires restart)
Entry: apps/main/src/main.ts
Output: .package/dist/main.cjs

Startup Sequence:

// apps/main/src/main.ts
app.whenReady().then(() => {
  registerAppProtocol();
  createWindow();
  setupIpcHandlers();
  initBackgroundServices();
});

Renderer Process - React UI

The renderer process (apps/renderer/src/main.tsx) is the UI layer that:

Renders the React application
Runs in a sandboxed browser environment
Cannot directly access Node.js APIs
Communicates with main via IPC (preload bridge)

Key Characteristics:

React 19 + Vite 7
TailwindCSS + Radix UI components
Hot-reload enabled in development
Sandboxed (no Node integration, context isolation enabled)
Entry: apps/renderer/src/main.tsx
Output: apps/renderer/dist/

Security Configuration:

webPreferences: {
  nodeIntegration: false,      // No Node.js in renderer
  contextIsolation: true,      // Isolate preload context
  sandbox: true,               // Enable sandbox
  preload: preloadPath,        // Secure bridge
}

Preload Scripts - Secure Bridge

The preload scripts (apps/preload/src/preload.ts) provide a secure bridge:

Run before renderer code loads
Have access to both Node.js and browser APIs
Expose safe IPC methods via contextBridge
Validate all requests/responses with Zod schemas

Key Characteristics:

TypeScript with strict validation
Exposes only whitelisted IPC channels
No direct Node.js access from renderer
Entry: apps/preload/src/preload.ts
Output: apps/preload/dist/preload.js

IPC Bridge Example:

// Expose safe IPC API to renderer
contextBridge.exposeInMainWorld('ipc', {
  invoke: (channel, args) => {
    validateRequest(channel, args);
    return ipcRenderer.invoke(channel, args);
  },
  send: (channel, args) => {
    validateRequest(channel, args);
    ipcRenderer.send(channel, args);
  },
});

Package Architecture

Rowboat uses a nested pnpm workspace structure where the Electron app (apps/x) is itself a monorepo with shared packages.

Workspace Structure

apps/x/
├── apps/
│   ├── main/              # Main process
│   ├── renderer/          # React UI
│   └── preload/           # Preload scripts
└── packages/
    ├── shared/            # @x/shared - Types, validators
    └── core/              # @x/core - Business logic

Build Dependencies

shared (no deps)
   ↓
core (depends on shared)
   ↓
preload (depends on shared)
   ↓
main (depends on shared, core)
renderer (depends on shared)

The npm run deps command builds packages in order: shared → core → preload. Always run this after modifying shared packages.

Package Responsibilities

@x/shared - Shared Types & Validators

Purpose: Type definitions, Zod schemas, and utilities shared across all packages.Contents:

IPC channel definitions and validators
Shared TypeScript types
Zod schemas for runtime validation
Common utilities

Location: apps/x/packages/shared/src/Usage:

import { ipc } from '@x/shared';
import type { AgentConfig } from '@x/shared';

@x/core - Business Logic

Purpose: Core business logic, AI integration, OAuth, and background services.Contents:

Knowledge graph processing
AI/LLM integration (Vercel AI SDK)
OAuth client implementations
Background sync services (Gmail, Calendar, Fireflies)
Configuration management
Agent runtime

Location: apps/x/packages/core/src/Key Modules:

knowledge/ - Knowledge graph and entity extraction
models/ - LLM provider integration
auth/ - OAuth 2.0 + PKCE flows
services/ - Background services
runs/ - Agent execution runtime

Build System

Why esbuild Bundling?

pnpm uses symlinks for workspace packages. Electron Forge’s dependency walker cannot follow these symlinks during packaging. esbuild bundles everything into a single file, eliminating the need for node_modules in the packaged app.

Build Tools

Layer	Tool	Purpose
Main	esbuild	Bundle to single CommonJS file
Renderer	Vite	Fast dev server, optimized builds
Preload	TypeScript	Compile to JavaScript
Packaging	Electron Forge	Create distributable (.dmg, .exe)

Development Commands

# Install dependencies
cd apps/x && pnpm install

# Build workspace packages
cd apps/x && npm run deps

# Start development server
cd apps/x && npm run dev

# Lint and type-check
cd apps/x && npm run lint

# Create production build
cd apps/x/apps/main && npm run package

# Create distributable
cd apps/x/apps/main && npm run make

Background Services

Rowboat runs several long-lived background services in the main process:

Service	Purpose	File
Gmail Sync	Fetch and index emails	`core/src/knowledge/sync_gmail.ts`
Calendar Sync	Fetch calendar events	`core/src/knowledge/sync_calendar.ts`
Fireflies Sync	Fetch meeting transcripts	`core/src/knowledge/sync_fireflies.ts`
Granola Sync	Fetch Granola notes	`core/src/knowledge/granola/sync.ts`
Graph Builder	Process content into knowledge graph	`core/src/knowledge/build_graph.ts`
Agent Runner	Execute scheduled agents	`core/src/agent-schedule/runner.ts`

Service Initialization:

// apps/main/src/main.ts
import { init as initGmailSync } from '@x/core/dist/knowledge/sync_gmail.js';
import { init as initGraphBuilder } from '@x/core/dist/knowledge/build_graph.js';

initGmailSync();         // Start Gmail sync loop
initGraphBuilder();      // Start graph processing loop

Tech Stack Summary

Layer	Technology
Desktop Framework	Electron 39.x
UI Framework	React 19
Styling	TailwindCSS, Radix UI
Build Tools	Vite 7, esbuild
Package Manager	pnpm (workspace protocol)
TypeScript	5.9 (ES2022 target)
AI SDK	Vercel AI SDK
OAuth	openid-client (RFC 7636 PKCE)
Packaging	Electron Forge

Key Design Principles

Security - Sandboxed Renderer

No Node.js in renderer: All Node operations go through IPC
Context isolation: Preload context separated from renderer
Sandbox enabled: Renderer runs in Chromium sandbox
Validated IPC: All messages validated with Zod schemas

Performance - Optimized Builds

Single-file bundling: esbuild creates one main.cjs file
Hot reload: Renderer changes reload instantly
Lazy loading: React components lazy-loaded where possible
Efficient IPC: Minimal data transfer between processes

Developer Experience

Type safety: Full TypeScript coverage
Schema validation: Runtime validation with Zod
Fast rebuilds: Vite HMR for instant feedback
Monorepo structure: Shared code in @x packages

Next Steps

Knowledge System Architecture - Deep dive into the knowledge graph
AI Integration - LLM provider integration details
OAuth Implementation - OAuth 2.0 + PKCE flows

Contributing

Architecture

Reference

Architecture Overview

Architecture Diagram

Electron Process Architecture

Package Architecture

Workspace Structure

Build Dependencies

Package Responsibilities

Build System

Why esbuild Bundling?

Build Tools

Development Commands

Background Services

Tech Stack Summary

Key Design Principles

Next Steps

Build docs developers (and LLMs) love

Contributing

Architecture

Reference

​Architecture Diagram

​Electron Process Architecture

​Package Architecture

​Workspace Structure

​Build Dependencies

​Package Responsibilities

​Build System

​Why esbuild Bundling?

​Build Tools

​Development Commands

​Background Services

​Tech Stack Summary

​Key Design Principles

​Next Steps

Build docs developers (and LLMs) love

Architecture Diagram

Electron Process Architecture

Package Architecture

Workspace Structure

Build Dependencies

Package Responsibilities

Build System

Why esbuild Bundling?

Build Tools

Development Commands

Background Services

Tech Stack Summary

Key Design Principles

Next Steps