radicle-gui

Monorepo for Radicle's graphical interfaces. It holds two independent projects, each with its own npm package, Cargo workspace, toolchain files, checks and conventions:

Explorer (explorer/): the Svelte web app for browsing Radicle repositories, its TypeScript HTTP client, and the radicle-httpd and radicle-search backends it talks to. See explorer/AGENTS.md.
Desktop (desktop/): the Tauri desktop app. See desktop/AGENTS.md.

This file covers what applies to both. Each project's AGENTS.md is the source of truth for anything inside it.

Layout

Path	What it is
`explorer/`	Web app, HTTP client, `radicle-httpd` and `radicle-search`
`desktop/`	Tauri app: Svelte frontend in `src/`, Rust in `crates/`
`docs/adr/`	Decisions that affect the whole repository
`.github/workflows/`	GitHub CI: `explorer-.yml` for explorer, `desktop-.yml` for desktop
`.buildkite/`	Radicle CI pipelines (explorer only)
`.ryph/`	Dev machine image and setup for agents, see `.ryph/environment.md`

Working in this repo

Work out which project a change belongs to first, and run every command from that project's directory. There are no root npm or cargo commands.
A change that touches both projects is two changes: check each project with its own commands.
Explorer's components use legacy Svelte syntax ($:, stores, export let), desktop's use Svelte 5 runes.
Record a bigger architectural change as a new ADR, numbered after the last one and in the same format: in docs/adr/ if it affects the whole repository, in the project's own docs/adr/ otherwise.
Before opening a patch or tagging a release, read CONTRIBUTING.md for patch labels and release tags. Never create or match the old releases/<version> tags; they predate the monorepo.

Shared conventions

Prefer undefined over null
Do not add comments unless explicitly asked. When writing comments, use proper English sentences
Ask before adding new dependencies: each one is a supply-chain risk, and installs are gated by min-release-age and strict-allow-scripts
Use npm, never yarn or pnpm: the lockfiles and .npmrc settings are npm's
Run tests through the npm run scripts, not npm test (neither project has one), npx vitest or npx playwright test: the scripts set TZ=UTC and, in explorer, NODE_CONFIG_ENV, which the tests rely on
Use ES private fields (#field), not the TypeScript private keyword

Svelte components

CSS: scoped styles with design tokens (var(--color-text-primary), var(--txt-body-m-regular), var(--border-radius-sm)); use :global() for styling slotted or {@html} content
Loading states: {#await promise} blocks for inline async; local loading boolean with try/catch for imperative fetches

Commit messages

Imperative mood: "Add feature" not "Added feature"
Capitalize subject, no trailing period, about 50 chars
Prefix commits that touch a single component with it: explorer:, httpd: or desktop:, e.g. "desktop: Add release view". Commits that span most of the repository have no prefix
Each commit should be understandable, testable and revertable on its own

Radicle ecosystem (sibling repos)

Both projects build on crates from sibling repositories, which may be checked out next to this one. If present, read their source when a type comes from outside this repo or you need protocol context:

../heartwood: the protocol. Crates radicle, radicle-cob, radicle-crypto and radicle-core. Start with HACKING.md and ARCHITECTURE.md
../radicle-git: radicle-surf, the code browsing (files, diffs, commits) that httpd and desktop serve
../radicle-job: CI job COBs
../rips: protocol specs: 0001-heartwood.md, 0002-identity.md, 0003-storage-layout.md
../radicle.dev: user docs. _guides/user.md covers workflows, _guides/protocol.md covers gossip, replication and the COB model, and _guides/seeder.md covers seed nodes and httpd setup

Domain glossary

RID — Repository ID (rad:z3gqc...)
DID — Decentralized Identifier, user identity (did:key:z6Mk...)
NID — Node ID, the public key in a DID
COB — Collaborative Object (issue, patch, or identity as a Git DAG)
Delegate — authorized repo maintainer; signatures determine canonical state
Patch — pull-request equivalent with immutable revisions and reviews
Seed — hosting/replicating a repo; seed nodes are always-on servers
Canonical refs — branches/tags resolved by delegate quorum

4.6 KiB Raw Blame History