jj-dojo architecture

For jj itself (commits, operations, conflicts and every command), see the jj architecture reference.

The whole extension on one page

Top to bottom: what the extension adds to VS Code, the extension host code behind it, the commit graph webview on the far side of a message boundary, the layers Google plans to add while open-sourcing the extension (dashed), and jj itself. Every box links to the page that explains it, or to the pinned source while that page is still being written.

At this pin the commit graph is the only open-sourced feature with a real UI, and nothing reads a jj repository yet. The host side of the webview protocol, createFakeWebviewState, answers $webviewReady with one hard-coded commit and is marked // TODO - Replace with a real implementation. The API and client layers that would fill it are planned in docs/intro.md.

The layers

VS Code contributions

package.json activates the extension on onStartupFinished and workspaceContains:.jj, runs it in the workspace extension host (extensionKind: ["workspace"]), and contributes one webview view, jj-dojo.commit-graph ("JJ Graph"), in the source control container, the commands jj.mergeConflict.acceptAllSides and jj.mergeConflict.acceptOneSide, and the colour jj.mergeConflict.thirdSideBackground. The configuration and menus blocks are empty. See activation.

Extension host

activate installs an output-channel logger as the global logger, logs the build version, and creates JjUi, pushing both onto context.subscriptions. JjUi is split in two: JjUiBase holds what Google's internal build shares (merge-conflict support), and JjUi adds the commit graph view provider with retainContextWhenHidden. The icon theme service and the utilities are compiled in, but nothing outside their own directories imports the icon theme service yet.

The message boundary

The host and the webview share no memory. Each side wraps postMessage in a Channel and hands it to VS Code's own RPC helper, vendored under third_party/vscode/rpc_protocol. The host gets a proxy for WebviewShape ($setState, $openSearchBox), and the webview a proxy for ExtensionShape ($webviewReady, $informNewOrder, $executeCommand, clicks, context menus, callouts). The webview calls $webviewReady as soon as it boots, and the host answers with state. See the graph webview protocol.

Commit graph webview

A Lit app (<jj-app>) receives each WebviewState, optionally narrows it with focus mode, lays it out with createCommitNodes, reports the resulting order back to the host, and renders a row per commit: tiles for the graph on the left, then chips, IDs and the description. See commit graph layout and the graph webview UI.

Planned API and client layers

Google's internal extension sits on an API layer (an ApiStateManager combining a WorkspaceStateManager cache, a PendingSnapshotsManager, an ActionsQueue that serialises writes, a file-system watcher, an op-head pubsub and a forge manager) over a client that talks gRPC-web to Google's jj servers. The open-source plan swaps that client for one that runs the jj CLI with templates, keeping reads side-effect free with --ignore-working-copy and --no-integrate-operation. The first pieces are in the tree but not wired into activation: a subprocess client under src/client/ that reads the commit graph, the file-system watcher under src/file_system_watcher/, and bare interfaces for an op-head watcher, a network-reconnect watcher and telemetry. See the externalization plan.

Repository map

Path	What's there	Page
`src/extension.ts`, `src/ui/ui.ts`	Entry point and feature registration	activation
`src/logging/`, `src/error/`	Global logger, output channel, error types	activation
`src/ui/commit_graph/api/`, `src/ui/commit_graph_provider/`	The webview protocol types and its host side	graph-protocol
`src/ui/commit_graph/algorithms/`	Layout, drawing, ranges, focus mode	graph-layout
`src/ui/commit_graph/components/`, `utils/`	Lit components of the webview	graph-webview
`src/ui/merge_conflict/`	Conflict-marker parsing, decorations, CodeLens, resolution	merge-conflicts
`src/ui/icon_theme_service/`	File-icon theme lookup for webviews	icon-theme
`src/client/`	The `Client` interface and the jj subprocess client, not yet wired in	roadmap
`src/api/`	The commit and repository-state types the client returns	roadmap
`src/op_head_watcher/`, `src/network_reconnect_watcher/`, `src/telemetry/`	One interface each, with no implementation yet	roadmap
`src/file_system_watcher/`	The planned API layer's file-system watcher: the interface and a `@parcel/watcher` implementation	roadmap
`src/utils/`	Hash collections, commit topology, checks, disposal, time	utils
`src/testing/`, `spec/`	Fake VS Code API and the Jasmine config	build-and-test
`tools/bazel/`, `BUILD.bazel`, `MODULE.bazel`	The Bazel build: TypeScript, Jasmine and addlicense rules	build-and-test
`third_party/vscode/`	Vendored VS Code code: the RPC protocol and enums	graph-protocol
`scripts/`	A generator for `third_party/vscode/vscode_enums.ts`	build-and-test
`docs/`	The externalization plan and its architecture drawing	roadmap

Implemented vs planned

Piece	Status at this pin
Commit graph webview, layout and protocol	Implemented and tested. The upstream plan marks it done.
Data for the commit graph	Fake: one hard-coded commit.
Merge-conflict highlighting and resolution	Implemented and registered on activation.
Icon theme service	Implemented and tested, not yet used by anything.
jj subprocess client	in progress per the plan. `SubprocessClient` snapshots the working copy without publishing an operation, reads the commits at that operation with a JSON `jj log` template, and reads file contents at a commit or by file ID. It has 28 tests against a real repository, but nothing in the extension calls it yet.
File-system watcher	in progress per the plan. The `FileSystemWatcher` interface and a `LocalFileSystemWatcher` built on `@parcel/watcher` are in the tree and tested, but nothing constructs one yet.
Op-head watcher (the plan's JJ PubSub)	in progress An interface only.
Other API-layer managers, mutating commands, commit dialog, split editor, forge integration	planned