Add ADRs for repository layout and shared UI code

Most copy-pasting between the two front-ends happens in UI code. These
propose making explorer and desktop siblings and sharing code from
source, without an npm workspace for now.
This commit is contained in:
Rūdolfs Ošiņš
2026-10-22 11:06:33 +02:00
parent 4a84871ee7
commit 954222cb11
2 changed files with 86 additions and 0 deletions
+40
View File
@@ -0,0 +1,40 @@
# 1. Repository layout
Date: 2026-10-21
## Status
Proposed
## Context
radicle-gui merged radicle-explorer and radicle-desktop. Explorer still
occupies the repository root, with desktop nested under `desktop/`. That
leaves no neutral place for project-wide docs or code shared between the two
front-ends, which is where most of the copy-pasting has happened.
## Decision
```
radicle-gui/
AGENTS.md
docs/
adr/
desktop/
explorer/
shared/
ui/
```
- Explorer moves from the root into `explorer/`, next to `desktop/`.
- The root holds only project-wide files: `AGENTS.md`, ADRs under `docs/adr/`,
and CI config.
- `shared/` holds code used by both front-ends. How the apps consume it is
decided in ADR 2.
- Each project keeps its own Cargo workspace, toolchain files and checks.
- `radicle-httpd` and `radicle-search` stay in `explorer/` for now. Moving
them out is a separate decision.
- Commits that touch a single component are prefixed with it: `explorer:`,
`httpd:` or `desktop:`. Commits that span most of the repository have no
prefix. Either way, a commit should be understandable, testable and
revertable as one coherent change.
+46
View File
@@ -0,0 +1,46 @@
# 2. Shared front-end code in an npm workspace
Date: 2026-10-21
## Status
Proposed
## Context
Desktop and explorer have copied a lot of front-end code from each other.
Desktop is the most developed of the two and already on Svelte 5, so it is the
source we extract shared code from.
We also considered consuming `shared/ui` as a plain source folder and as a
local `file:` dependency. Both need workarounds in each app's Vite and
TypeScript config, and leave `shared/ui` without its own lints and tests.
## Decision
A root npm workspace holds `shared/ui`, `explorer` and `desktop`, with one
lockfile, `.npmrc` and `.nvmrc` at the root.
`shared/ui` is the package `@radicle-gui/ui`. It has `svelte` as a peer
dependency and its own checks, lints, tests and CI workflow. The apps depend on
it and import it from source, without a build step.
Shared stylesheets and fonts live in `shared/ui/public`. A Vite plugin from the
package serves them next to each app's public directory in dev and adds them
to the build, so the apps keep their `<link>` tags, marked `vite-ignore`.
Shared code must not import `@tauri-apps/*`, `@bindings` or `@http-client`.
It takes plain props, and each app adapts its own data to them.
## Consequences
- The apps share one dependency tree. Shared code gets a single copy of
`svelte` and its other dependencies, and is checked and tested on its own,
without workarounds in either app.
- Dependency versions are coupled. Where the apps' ranges overlap, a bump lands
in both, and an app that needs to diverge has to pin its own version.
- Installs and builds start from the repository root. Working on one app means
installing it with `-w`, and Nix, Docker and CI have to use the root
lockfile.
- Shared components are written with runes. Explorer can render them while it
still uses legacy syntax, at the cost of some friction where the two meet.