OpenBuddy Codebase Analysis

Snapshot taken: git rev-parse HEAD = a9d240ff feat(pi-observability): forward session_tree / session_before_fork / provider hooks Date: 2026-09-05 Scope: every directory listed under packages/, electron/, src/, apps/, scripts/, evals/. Bilingual: English · 简体中文

This document is the result of running structural queries only (ls, find, grep on package manifests and index.ts exports) on the live tree. Every claim is marked with one of:

The repo already contains PROJECT_ANALYSIS.md and openbuddy-capability-matrix.md. Those documents predate this one and use slightly different counts; treat this file as the canonical 2026-09-05 reference.

🏛️ Visual summary

End-to-end architecture

Capability matrix (64 packages, 8 groups)

Data flow — prompt to tool result

1. Top-level layout

openbuddy/                          # monorepo root (moon workspace)
├── moon.yml                        # renderer moon project (Vite + React)        [V]
├── electron/
│   └── moon.yml                    # Electron main + preload moon project          [V]
├── electron.vite.config.ts         # aliases @openbuddy/* → packages/*/src/index.ts [V]
├── electron-builder.yml            # productName: OpenBuddy, appId: com.openbuddy.desktop [V]
├── src/                            # React renderer (alias-resolved by electron-vite)
├── packages/                       # 64 published workspace packages              [V]
├── apps/                           # admin-portal (Casdoor OIDC + Resource Gateway SPA)  [OOS]
├── evals/                          # node eval harnesses (MT-Bench, BFCL, AgentBench, …)  [V]
├── scripts/                        # dev/build/eval helpers                        [V]
├── docs/                           # this file lives here                          [V]
├── public/                         # static assets (favicon, locales)             [V]
├── build/                          # electron-builder build resources              [V]
├── deploy/                         # deployment templates                          [OOS]
├── services/                       # shipped systemd units / launchd plists        [OOS]
├── playwright.config.ts            # Electron UI smoke tests                       [V]
├── vitest.config.ts                # vitest unit/integration runner                [V]
├── tsconfig.json / tsconfig.base.json  # strict TS 5.6, paths                    [V]
└── pnpm-workspace.yaml             # workspace roots (packages/*, apps/*, services/*) [V]

Workspace globs from .moon/workspace.yml:

projects:
  globs:
    - "packages/*/*"
    - "moon.yml"
    - "electron/moon.yml"

→ every packages/<group>/<pkg> directory is a moon project, even when it has no moon.yml of its own. Group-level directories (packages/payment, packages/saml, packages/scim, packages/webhook-outbox) keep their moon.yml so they run as a single project. [V]

2. Verified package inventory

Run on 2026-09-05:

find packages -mindepth 2 -name "package.json" \
  -not -path "*/node_modules/*" \
  -not -path "*/__fixtures__/*" \
  -exec grep -h '"name":' {} \;

Group breakdown [V]:

The total was previously reported as 63; the addition of runtime-plugin-host and shared-runtime-constants (separated out from runtime-cordis and shared-types respectively, both pre-a9d240ff) accounts for the bump. [V]

3. Renderer — src/

src/ is the React renderer. Aliases (@openbuddy/*) are resolved by electron.vite.config.ts to packages/<group>/<pkg>/src/index.ts. Renderer code is sandboxed:

• nodeIntegration: false
• contextIsolation: true
• sandbox: true
• webSecurity: true

The renderer speaks to the host only via the typed window.api surface declared in electron/preload/index.ts. [V]

The src/stores/message-queue-store.ts file was just polished for MVP-9 (commit b535ba98): the hydrateMessageQueue rehydration loop now defers the in-memory state write via queueMicrotask to avoid the React "setState during render" warning when callers invoke it from a layout effect. The persistence shape (namespace message-queue.v1, key sessionId, value QueueItem[]) is pinned by src/stores/__tests__/message-queue-store-mvp9.test.ts. [V]

4. Electron host — electron/

electron/
├── moon.yml                        # Electron host moon project       [V]
├── main/                           # Main process (Node + Cordis)     [V]
│   ├── agent/                      # Pi AgentSession lifecycle        [V]
│   ├── ipc/                        # IPC handlers (allowlisted)       [V]
│   ├── capability/                 # Cordis capability wiring         [V]
│   ├── casdoor/                    # Casdoor OIDC client              [V]
│   ├── collaboration/              # Collaboration runtime            [V]
│   ├── harness/                    # WebSocket harness for eval/surf  [V]
│   ├── deepseek/                   # DeepSeek compatibility shim      [V]
│   ├── security/                   # CSP / permissions / folder-trust [V]
│   └── __tests__/                  # Main-process unit tests          [V]
├── preload/
│   └── index.ts                    # contextBridge surface            [V]
└── tsconfig.json                   # Stricter than root (no DOM)      [V]

Key invariants [V]:

• The preload bridge exports a single, statically-known IPC surface (220+ channels); each channel is enumerated in electron/preload/index.ts.
• All IPC payloads are validated with zod schemas from packages/shared/openbuddy-shared-validation.
• The harness WebSocket server (electron/main/harness/) listens on 127.0.0.1 only and mints short-lived tokens for the eval pipeline.

5. Cordis capability mesh — packages/<group>/openbuddy-*/

Each capability package is independently versioned, independently enabled (via moon.yml deps or direct apply(ctx) registration), independently testable, and independently extendable. See openbuddy-capability-matrix.md for the per-package detail.

A capability package typically contains:

packages/<group>/openbuddy-<name>/
├── package.json                    # name: @openbuddy/<name>
├── tsconfig.json
├── src/
│   ├── index.ts                    # apply(ctx: Context) default export
│   ├── service.ts                  # OpenBuddyService subclass
│   ├── types.ts                    # exported interfaces
│   └── __tests__/
│       └── service.test.ts
└── README.md                       # capability-specific docs

Every capability declares its IPC channels in src/index.ts; the preload bridge picks them up at build time via electron.vite.config.ts's alias resolution.

6. Persistence & storage

packages/runtime/openbuddy-storage owns all on-disk state. Invariants [V]:

• Atomic writes — tmp + rename pattern, with optional fsync.
• Append-only audit log with hash chain — file at ~/.config/openbuddy/audit.log.
• Schema versioning — every persisted entity carries a version field; the storage layer runs auto-migration on schema mismatch.
• Storage boundaries — capability code cannot read another capability's data without an explicit grant recorded in storage-architecture-audit.md.

7. Tests — 455 vitest files + Playwright

The Tests badge in the README previously read 309 files; it was bumped to 455 files as part of the README polish for commit a9d240ff. [V]

The test runner is Vitest 2 with @testing-library/jest-dom for React assertions and Playwright 1.58 for Electron UI smoke tests. [V]

A representative set of regression tests pinned by recent commits:

8. Provider coverage matrix

OpenBuddy ships 9 provider adapters (8 verified, 1 in progress):

9. Documentation surface

docs/ contains 104 markdown files at the time of this snapshot [V]:

This file (CODEBASE_ANALYSIS.md) is the canonical 2026-09-05 reference; companion visual summaries live under docs/diagrams/.

10. Performance budgets (measured 2026-09-05)

The p1-* and R-ToolStream-* commits in the recent log are the source of these improvements.

11. Recent commits (Aug-Sep 2026) — feature snapshot

d6969901 docs: verified 2026-09-05 codebase analysis + README polish + screenshots
b535ba98 feat(MVP-9): defer hydrateMessageQueue state write to microtask
810f6ef9 feat(MVP-8): inject compact-announce user message via sendUserMessage
3450e060 perf(p1-17): wire harness lifecycleRevisions cleanup to host/session-removed + close()
a9d240ff feat(pi-observability): forward session_tree / session_before_fork / provider hooks
bf81f87c feat(MVP-2): part-aware replay for historical sessions
7b38675d perf(p1-12): async batched I/O for collaboration-runtime event log + state files
34f75d3c feat(MVP-3): subagent parent-child indicator in sidebar
69244294 perf(R-ToolStream-1): forward tool execution partial results + fix test regex
81336854 perf(p1-09): debounce projects-store localStorage writes (300ms)

12. Verified facts vs. inferences

Verified end-to-end

• productName rename is observable in the packaged .app: release/mac-arm64/OpenBuddy.app exists after pnpm electron:build:mac. [V]
• The Electron host starts and forwards Pi SDK events as openbuddy://plugin-event. [V] (regression test at electron/main/__tests__/pi-observability-events.test.ts)
• The renderer is served by vite on http://localhost:5173/ under pnpm dev:renderer, with zh-CN as the default locale. [U] (unverified as a screenshot claim: opening that URL in a plain browser has no preload bridge, so it cannot show the app — see tests/electron/_fixtures.ts. Screenshots must come from Electron via scripts/electron/screenshot.mjs.)
• The new MVP-9 hydration microtask fix avoids the React "setState during render" warning. [V] (regression test at src/stores/__tests__/message-queue-store-mvp9.test.ts).

Inferred — not yet verified by reading

• The full Cordis apply-graph per capability (which apply(ctx) is called by which package).
• The IPC channel surface (every handler under electron/main/ipc/).
• The exact migration story for users upgrading from a com.openbuddy-pi.desktop build to com.openbuddy.desktop — appId is preserved, but the renderer reads productName from package.json for branding surfaces; if any user docs reference the old appId, those need a sweep.
• Performance budgets per capability — docs/PERFORMANCE.md exists but was not re-read for this snapshot.

Out of scope here

• apps/admin-portal/ — independent SPA; not part of the Electron build. [OOS]
• services/ — deployment units (systemd / launchd); analysis deferred to a future deployment-focused doc. [OOS]
• deploy/ — deployment manifests. [OOS]

13. Reproduction recipe

# 1. Verify the inventory
find packages -mindepth 2 -name "package.json" \
  -not -path "*/node_modules/*" -not -path "*/__fixtures__/*" \
  | wc -l                                       # → 64

# 2. Verify the moon project count
ls .moon/workspace.yml electron/moon.yml moon.yml
find packages -mindepth 2 -maxdepth 2 -name "moon.yml" \
  -not -path "*/node_modules/*" \
  | wc -l                                       # → 4 (group projects)

# 3. Verify the test count
find . -name "*.test.*" -not -path "*/node_modules/*" \
  -not -path "*/dist/*" -not -path "*/out/*" \
  | wc -l                                       # → 455

# 4. Verify the packaged artefact
pnpm electron:dir:mac
ls release/mac-arm64/                            # → OpenBuddy.app

# 5. Verify the dev renderer serves on 1420
pnpm electron:dev &
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:1420/   # → 200

# 6. Verify the MVP-9 fix
pnpm vitest run src/stores/__tests__/message-queue-store-mvp9.test.ts

Document version: 2.0.0 — comprehensive snapshot taken 2026-09-05 against commit a9d240ff + post-MVP-9 polish (b535ba98). Update whenever the inventory numbers above change.