# Architecture

> How GUIJam is built. A widget in a shadow root, a dev server plugin, the gjd daemon written in Rust, and your AI coding CLI running headlessly.

GUIJam is four pieces, each with one job. Only one of them ever writes to your project.

GUIJam widget (browser, in a shadow root) → guijam() plugin (your dev server, over the HMR channel) → gjd daemon (Rust, localhost only, WebSocket with a per-session token) → your AI CLI (headless, no write tools, over stdio).

## The widget

The toolbar and panels run in your page, inside a shadow root, so your app's styles never leak into them and theirs never leak out. The widget is built with React and FigUI, a set of Figma-style components.

It talks only to your dev server: over Vite's hot-reload channel, or through a localhost relay in Next.js. It has no endpoint of its own and no token in page JavaScript.

## The dev server plugin

`guijam()` in Vite, the Nuxt module, the Astro integration and `withGuijam()` in Next.js all do the same three things:

- **Add source locations** to elements, so each one knows the file, line and column that rendered it. See [Source locations](https://guijam.francistinao.com/docs/concepts/source-locations).
- **Serve previews from memory** in place of the files on disk. See [Live previews](https://guijam.francistinao.com/docs/concepts/live-previews).
- **Report whether each hot update succeeded**, so a broken preview never reaches the page silently.

In Next.js, `withGuijam()` adds a loader that marks elements and serves previews, loads the toolbar through `instrumentationClientInject`, and starts a relay on localhost that connects the page to `gjd` with a per-session token.

## The gjd daemon

`gjd` is a small Rust program, installed with the `guijam` package for your platform. It's the only process that writes to your project. It:

- Reads the source of the element you picked.
- Routes each request: an exact edit it can make itself, or a request for your CLI. See [Request lifecycle](https://guijam.francistinao.com/docs/concepts/request-lifecycle).
- Runs your CLI and validates every edit it proposes against the current file.
- Journals each commit, so [undo](https://guijam.francistinao.com/docs/guides/undo) restores files exactly.

It listens on localhost only, requires a per-session token, and stops after 30 minutes with no dev server connected. There is one daemon per project.

When the dev server starts and finds a daemon from another GUIJam version still running, it stops that one and starts the version you installed, so an upgrade takes effect on your next dev server start. When the daemon stops, any AI tool run still in progress stops with it, so nothing keeps using your plan in the background.

## Your AI CLI

Your CLI receives the relevant code inline and answers with structured edits. It's never given tools that can change files. See [AI tools](https://guijam.francistinao.com/docs/ai-tools).

## One message format

The widget, the plugin and the daemon share one set of message definitions, written as JSON Schemas. TypeScript and Rust types are generated from them, so the three processes can't drift apart.
