rowboat/ARCHITECTURE.md

Architecture

This repository contains multiple Rowboat product surfaces. The quickest way to get oriented is to start from the table below instead of treating the repo as a single application.

Product Map

Surface	Path	Status	Purpose
Desktop app	apps/x	Primary	Local-first Electron app with Markdown memory, knowledge graph sync, and on-device workflows
Hosted web app	apps/rowboat	Active	Next.js platform with project-scoped agents, RAG, jobs, billing, and integrations
CLI/runtime	apps/cli	Active	Local HTTP runtime, workflow packaging, and npm-distributed rowboatx tooling
New frontend	apps/rowboatx	Active, evolving	Static Next.js UI that talks to the local runtime and shell-provided APIs
Docs	apps/docs	Active	Mintlify documentation site
Python SDK	apps/python-sdk	Supporting	Thin Python client for the hosted chat API
Experiments	apps/experimental	Experimental	Prototypes and one-off services not considered part of the core product

How The Pieces Fit Together

apps/x

• Nested pnpm workspace for the desktop product.
• apps/main runs the Electron main process.
• apps/preload exposes the validated IPC bridge.
• apps/renderer contains the React UI.
• packages/shared holds shared schemas and IPC contracts.
• packages/core contains workspace, knowledge graph, agent, and integration logic.

apps/rowboat

• Hosted or self-hosted Next.js application.
• Uses MongoDB, Redis, Qdrant, uploads storage, background workers, and external providers.
• Organized into application, entities, infrastructure, and interface-adapters layers.

apps/cli + apps/rowboatx

• apps/cli provides the local API and runtime for runs, tools, permissions, and event streaming.
• apps/rowboatx is the browser UI that expects a runtime behind /api/stream, /api/rowboat/*, or a configured window.config.apiBase.

Shared Runtime Concepts

• Local data lives under ~/.rowboat by default.
• The desktop product stores knowledge as Markdown files and maintains Git-backed history for those notes.
• The hosted app uses project-scoped data stores instead of the desktop Markdown vault.
• Both the desktop and hosted surfaces rely on model/provider abstraction, tool calling, and external integrations.

Recommended Entry Points

• Working on desktop memory, sync, or Electron UX: start in apps/x
• Working on hosted APIs, jobs, RAG, or project management: start in apps/rowboat
• Working on local runtime, SSE events, or packaging flows: start in apps/cli
• Working on the newer dashboard UI for the local runtime: start in apps/rowboatx

Common Commands

Desktop app

cd apps/x
pnpm install
npm run verify
npm run dev
npm run test

Hosted web app

cd apps/rowboat
npm install
npm run verify
npm run dev

CLI runtime

cd apps/cli
npm install
npm run verify
npm run server

Local runtime frontend

cd apps/rowboatx
npm install
npm run dev

Contributor Rules Of Thumb

• Prefer apps/x when the change is local-first or knowledge-vault oriented.
• Prefer apps/rowboat when the change requires server-side persistence, auth, billing, or hosted APIs.
• Treat apps/experimental as non-core unless you are intentionally working on a prototype.
• When adding documentation, update the README closest to the surface you changed.