Skip to content

Architecture

Wijanarko Putra Rajeb edited this page Oct 31, 2026 · 2 revisions

Architecture

src/
├─ client/    Preact UI — zero React packages
│  ├─ components/   layout, workspace, settings, mobile, common
│  ├─ hooks/        chat, workspace, ui, browser, models, settings
│  ├─ data/         mock datasets, samples, themes, model + agent catalogs
│  └─ tailwind.css  theme tokens (--theme-ink, --theme-paper, …)
├─ server/    Bun-only — Elysia routes, SQLite, omp RPC bridge, fs/git/terminal
│  ├─ routes/       one plugin per domain, mounted in routes/index.ts
│  ├─ lib/          omp session/subagent/config, panels, wiki, updates, lifecycle
│  └─ plugins/      SSR shell, static assets, compression, dev assets
├─ shared/    Imported by both — types, chat timeline folding, pure helpers
└─ cli/       kabmo command (plain ESM, runs under Bun)

packages/
├─ kabmo-sdk/   the panel-plugin contract (types, backend API, slots)
└─ kabmo-ui/    the Preact kit a plugin builds against

marketplace/plugins/
├─ command-runner/  a repository's commands, 18 sources across 15 toolchains
├─ stats/           CPU and RAM of the whole omp stack
└─ session-info/    active workspace and a note per session

One process serves everything: Elysia owns the API, the agent event stream is a WebSocket route on the same listener (SSE as fallback), and Bun bundles and serves the client from that same listener.

Non-obvious invariants worth reading before you edit

  • src/shared/** must never import a node: builtin or bun:sqlite — it also runs in the browser. Server-only helpers belong in src/server/lib/**.
  • Route modules keep the ported Remix shape (loader for GET, action for mutations) so status codes stay identical; action owns method dispatch and returns its own 405.
  • Every internal import uses the @/ alias, folders mirror component names in kebab-case, and every .ts/.tsx file stays under 350 lines.
  • Every right-panel view is a plugin, including the eleven Kabmo ships: one catalog merges the built-ins and the installed ones, so a view cannot be a table in one layout and a fetch in the other.
  • Nothing about a subsystem is designed twice. A rule stated at one call site and restated at another drifts silently; the wiki pages record which rules exist and why, measured.
  • A Bun process's RSS is not the memory it is using — the sweep and the health payload read the OS's PHYSICAL FOOTPRINT. Measured on this machine against a live server that had read and dropped transcripts: ps RSS 752 MB while vmmap -summary charged the process 70.6 MB (JS heap 24 MB), and Bun.gc(true) moved nothing — the sweep logged swept 1049 MB → 1050 MB every minute for hours, then the same process's RSS fell to 134 MB on its own when the OS reclaimed the clean pages. So src/server/lib/lifecycle/memory.ts applies KABMO_MEMORY_CEILING_MB (default 1024) to the footprint, reports rssMB beside it as a diagnostic, and caches the reading for 30 s because the probe is a spawn: footprint -p <pid> on macOS (78 ms; its headline matched vmmap exactly, 122 MB against 121.6 MB), Pss from /proc/self/smaps_rollup on Linux with VmRSS as the fallback, and the runtime's own number on Windows. GET /api/health therefore carries memory.footprintMB; a number like "kabmo serve uses 1 GB" is usually the first one, not the second.

Where to read next

Topic Page
Bun-only runtime, node:* vs Bun APIs, toolchain commands Runtime and toolchain
Layout, sidebar, headers, composer, editor App shell and layout
Chat timeline, transports, tool cards, injected entries Chat stream and tools
omp settings, model roles, standby processes, updates omp engine and settings
Panel plugins, skills, BTW, scheduled tasks, PTY terminal Plugins, skills and automation
Tray, login entry, OS document handling Desktop integration
Repo scope, source control, worktrees, search Workspace panels
Provider settings, dialects, usage, marks Providers
Command runner, ask dialog, approval gate, todo, wiki Tool panels
Build loop, dev assets, browser E2E Build, test and release internals
Commits, releases, package publishing, bot Releases and workflows
File/folder/import rules and verification gates Codebase rules

Clone this wiki locally