Architecture

┌──────────────────────────────────────────────────────────────┐
│  React Renderer (src/, packages/ui/*)                        │
│    Vite + React 18 + Zustand stores                          │
│    Foundation: --wb-* tokens, 207-icon set, brand atoms      │
└──────────────────────┬───────────────────────────────────────┘
                       │  window.api  (typed contextBridge)
┌──────────────────────┴───────────────────────────────────────┐
│  Electron Main + preload bridge                              │
│    ipc.ts                ← allowlisted IPC handlers          │
│    agent-host.ts         ← Pi AgentSession lifecycle         │
│    pi-event-bridge.ts    ← cleanup-aware pi://* events       │
│    pi-resources.ts       ← local persistence (Cordis fs)     │
│    capability-*.ts       ← Cordis capability services        │
└──────────────────────┬───────────────────────────────────────┘
                       │  typed Pi session events
┌──────────────────────┴───────────────────────────────────────┐
│  Pi AgentSession + Cordis capability services                │
│    providers, tools, permissions, plans, tasks, persistence  │
└──────────────────────────────────────────────────────────────┘

src/
├── App.tsx                     # Root component
├── main.tsx                    # Vite entry
├── styles/
│   ├── tokens.css              # --wb-* design tokens
│   ├── global.css              # Reset + base
│   └── app.css                 # App layout
├── foundation/
│   └── components/Icon/        # 207-icon set
├── lib/
│   ├── pi-client.ts            # Streaming event client
│   ├── electron-api.ts         # Typed window.api wrapper
│   └── newapi-provider.ts      # NewAPI BYOK adapter
├── stores/
│   ├── session.ts              # Active session
│   ├── sessions.ts             # Session list
│   ├── permission.ts           # Permission prompts
│   └── …
├── components/
│   ├── Topbar.tsx
│   ├── Sidebar.tsx
│   ├── HomePage.tsx
│   ├── ChatView.tsx
│   └── Composer.tsx
└── locales/                    # i18n messages

// electron/preload/index.ts
const allowedInvokeChannels = new Set([
  "agent:abort", "agent:init", "agent:prompt", …
  "casdoor:authorize", "casdoor:login", …
  "collaboration:snapshot", "collaboration:task-control", …
  "session_fork", "session_search", …
  "memory:get", "memory:save", …
  "skills:list", "skills:add", …
  "tasks:list", "tasks:add", …
  "calendar:list", "calendar:create", …
  "email:drafts", "email:send", …
  "shellfs:read-text", "shellfs:write-text", …
  "dialog:open", "dialog:save", …
]);

electron/
├── main/
│   ├── index.ts                # App lifecycle entry
│   ├── window.ts               # BrowserWindow factory
│   ├── ipc.ts                  # IPC handlers (single file aggregating all)
│   ├── agent-host.ts           # Pi AgentSession lifecycle
│   ├── pi-event-bridge.ts      # pi://* event emitter
│   ├── pi-resources.ts         # Cordis fs persistence
│   ├── capability-*.ts         # One file per Cordis capability
│   ├── security/               # sandbox, CSP helpers
│   ├── collaboration/               # A2A message handlers
│   ├── session/                # session storage
│   └── __tests__/              # Vitest specs for main
├── preload/
│   └── index.ts                # contextBridge surface (allowlist)
├── collaboration-process.vite.config.ts
└── moon.yml                    # Electron host moon project

// A typical capability
import { Context, OpenBuddyService } from "@openbuddy/cordis";

export interface Config {
  defaultTimeoutMs: number;
}

export class MemoryService extends OpenBuddyService {
  static config: Config = {
    defaultTimeoutMs: 30_000,
  };

  constructor(ctx: Context, options?: Partial<Config>) {
    super(ctx, "openbuddy.capability.memory", options);
    this.cache = new Map();
  }

  async recall(query: string): Promise<string[]> {
    return this.cache.get(query) ?? [];
  }

  async remember(key: string, value: string) {
    this.cache.set(key, [value]);
    this.ctx.emit("memory:written", { key, value });
  }
}

export default function apply(ctx: Context) {
  ctx.plugin(MemoryService, ctx.config);
}

packages/
├── runtime/
│   ├── openbuddy-cordis/       # Cordis helpers, shared context
│   ├── openbuddy-plugin-host/  # plugin discovery + hot reload
│   └── openbuddy-storage/      # local fs persistence with audit
├── renderer/
│   └── openbuddy-renderer-host/# preload bridge glue
├── bundle/
│   └── openbuddy-base/         # umbrella for renderer-only deps
├── auth/
│   ├── openbuddy-casdoor/      # OIDC client + admin REST
│   └── openbuddy-permission/   # permission prompts & policy
├── core/
│   └── openbuddy-session/      # session lifecycle
├── team/
│   ├── openbuddy-team/         # multi-agent team
│   └── openbuddy-subagent/     # sub-agent spawning
├── capability/
│   ├── openbuddy-memory/       # long-term memory
│   ├── openbuddy-notification/ # inbox + native notifications
│   ├── openbuddy-plan/         # plan mode
│   ├── openbuddy-task/         # sub-agent tasks
│   ├── openbuddy-automation/   # local scheduler
│   ├── openbuddy-web-search/   # provider-pluggable web search
│   ├── openbuddy-inspiration/  # prompt templates
│   ├── openbuddy-folder-trust/ # per-folder permissions
│   ├── openbuddy-authorization/# capability-level policy
│   ├── openbuddy-mcp-client/   # MCP connector governance
│   ├── openbuddy-calendar/     # calendar
│   └── openbuddy-email/        # email
├── fs/
│   └── openbuddy-fs-local/     # local fs via Cordis
├── shared/
│   ├── openbuddy-files-kb/     # knowledge-base file indexing
│   └── openbuddy-types/        # cross-package types
├── collaboration/
│   ├── openbuddy-coordinator/  # coordination layer
│   ├── openbuddy-evidence/     # audit evidence
│   ├── openbuddy-inbox/        # cross-agent inbox
│   ├── openbuddy-network/      # network topology
│   ├── openbuddy-policy/       # cross-agent policy
│   ├── openbuddy-protocol/     # A2A message envelopes
│   ├── openbuddy-room/         # shared rooms
│   └── openbuddy-task/         # cross-agent task graph
├── payment/                    # Stripe / WeChat Pay / Alipay / HMAC
├── saml/                       # SAML 2.0 primitives
├── scim/                       # SCIM v2 endpoints
├── webhook-outbox/             # transactional outbox
└── ui/                         # 26 UI packages

1. User types in Composer.tsx
2. Composer calls window.api.invoke("agent:prompt", { text, context })
3. preload/index.ts forwards to ipc.ts handler "agent:prompt"
4. agent-host.ts invokes the Pi AgentSession.prompt() method
5. Pi decides: "call tool `read_file(path=…)/..."
6. AgentSession calls Cordis context.plugin(FileService).read(path)
7. FileService uses @openbuddy/fs-fs-local to read from disk
8. Permission check: is path inside a folder the user has granted trust for?
   ├─ Yes → proceed
   └─ No → emit permission:request event → renderer shows modal
9. Pi calls LLM (Anthropic / OpenAI / NewAPI) with the result
10. LLM streams back the summary
11. AgentSession emits pi://message-delta events
12. pi-event-bridge forwards to renderer via webContents.send
13. ChatView.tsx appends the delta to the visible message
14. AgentSession emits pi://done when finished
15. Composer stores the result in @openbuddy/capability-memory