Architecture

A desktop app on ADE CORE runs in three places: the Electron main process, a backend for the long-running work, and one or more windows. Each package runs in one of them; Database has a part in two.

Three places

Place	What runs there	Packages
Main process	The app's lifecycle, its menu, its windows, updates and the guards around each page	Shell, Service
Backend	Agent CLIs, language servers, database connections, files	Agents, the host of Database, LSP, Utils
Window	Everything a person sees	UI, Agent views, Editor views, Charts, Terminal, the views of Database

The backend can be the main process itself, an Electron utility process, or a separate Bun or Node process that a service keeps running. The packages work in any of them, because none opens a channel on its own.

The app owns every channel

No package registers an IPC handler or listens to an app-wide Electron event. A host takes a port or a request and answers it; a view takes a transport. The app connects the two over its own IPC and checks the sender on each channel.

That keeps the security decisions in one place, the app. A package that listened by itself would bypass the app's sender check.

window                         main process or backend
──────                         ───────────────────────
ChatClient ── transport ──▶ app IPC (sender check) ──▶ AgentHost.connect(port)
DatabaseProvider ─ client ─▶ app IPC (sender check) ──▶ host.handle(request, owner)
EditorView ── language service ──▶ LspSession ── transport ──▶ language server

• An agent chat: Agent views talk through a ChatTransport. AgentHost serves a FramePort in the backend and starts the provider CLIs.
• A database: the page's client sends requests that the app hands to the host. The host talks to the databases through a native helper, see Database.
• An editor: Editor views ask an injected language service. An LSP session can answer it, over a WebSocket from the window or over the stdio of a server process the backend started.

Contracts in between

What crosses a process boundary is described once, in a package that imports nothing from either side. Agent contracts holds the schemas of chats, accounts and usage. The database keeps its protocol in @adecore/database/protocol, and the shell keeps the shapes that reach a preload in @adecore/shell/bridge, which never imports Electron.

Both sides validate against the same schemas, so a host and a view from the same release always agree.

Cores without a DOM

The document models run anywhere: Editor core, Merge, Drawing, Diagram and Plan. A backend can apply an agent's edit, a test can check it, and a view can draw it, all on the same code.

One theme

Every view draws on the tokens of @adecore/ui/theme.css. The theme is neutral; the app sets its own accent, and light and dark follow data-theme on <html>. Packages with their own stylesheet, such as the terminal or the editor, read the same tokens. See Styles.

Where to next

• Choosing packages picks the packages for what you build.
• Installing and Styles set up an app.
• Each package's getting started page wires it end to end.