Project
Architecture
How the workspace is layered, and why the desktop app isn't a second backend.
riff is a Rust workspace (edition 2024) with a React UI. It is layered so the diff engine has no UI dependencies and the GitHub layer has no git or UI dependencies.
Crates
| Crate | Role |
|---|---|
riff-config |
The global config.toml: loading, defaults and the assist and Jira settings. Loading never panics. |
riff-state |
Preferences, projects, snoozes and the cache directory. |
riff-engine |
Core library: file and git diffing, intra-line word diff, syntax highlighting, conflicts, structural diff. Everything it produces is a serializable model. |
riff-forge |
Provider-agnostic GitHub layer over HTTPS (a few read calls still shell out to gh), plus the PR diff cache. It resolves the GitHub token. |
riff-core |
What riff knows about PRs: the list searches, the inbox and its ranking, one PR’s checks, reviews and threads, Jira tickets and dependencies. Shared by the server and the CLI. |
riff-assist |
LLM review assist: the Walkthrough article, review groups and notes, per-hunk review tags, and the recipe pipeline behind riff prepare --recipe. |
riff-scrutiny |
Scrutiny, the default reviewer behind Prepare. |
riff-jira |
Read-only Jira Cloud client. |
riff-review-store |
The on-disk review store: comments, drafts, viewed marks. |
riff-overview |
Cross-project summaries for the Overview dashboard. |
riff-web |
The axum server: the /api surface plus the embedded UI bundle. Also the riff-web binary, with prepare and article. |
riff-desktop |
The Tauri shell around riff-web; it builds the riff binary and runs riff pr and riff review in-process. |
riff-cli |
The riff-diff binary: the non-interactive diff printer, plus the pr and review commands. |
The UI lives in riff-app (React, Tailwind, Base UI, state in BlaC cubits). riff-web embeds its bundle at compile time; the desktop app loads it from there.
Dependency direction
riff-desktop → riff-web, riff-cli (and riff-state, riff-overview, riff-forge, riff-config)riff-web → riff-core, riff-engine, riff-forge, riff-assist, riff-scrutiny, riff-jira, riff-review-store, riff-overview, riff-state, riff-configriff-cli → riff-core, riff-engine, riff-forge, riff-review-storeriff-core → riff-forge, riff-state, riff-overview, riff-config, riff-jirariff-scrutiny → riff-assist, riff-engine, riff-jirariff-assist → riff-engine, riff-forge, riff-configThe engine has no UI or GitHub dependencies, and nothing below riff-web depends on a frontend. riff-review-store depends on no other riff crate.
One backend
The desktop app does not reimplement the API. It starts riff-web in-process on an ephemeral loopback port and points its window at it, so the page and the API share an origin and every fetch('/api/…') works the same in the app and the browser. Adding a feature means adding an HTTP route, never a desktop-only command.
A server binds one repository for its lifetime. Opening another repository starts a separate server rather than switching the first one over. With no repository the server still runs, so the project list, Overview and PR review work.
The exception is the no-repository surfaces (preferences, projects, overview and GitHub token entry): they also have a desktop command, because a window whose server failed to start still has to render. Both are thin wrappers over a shared crate.
Safety properties
- The structural diff can never hang the process. Parsing runs under strict size and time caps and inside
catch_unwind; when it can’t proceed safely it falls back to the line diff. - Config load never panics. A malformed or missing config leaves the server running with the affected features off.
- The GitHub token never goes into argv. git receives it through environment config, because argv is readable by any process of the same user.