riff

    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-config
    riff-cli → riff-core, riff-engine, riff-forge, riff-review-store
    riff-core → riff-forge, riff-state, riff-overview, riff-config, riff-jira
    riff-scrutiny → riff-assist, riff-engine, riff-jira
    riff-assist → riff-engine, riff-forge, riff-config

    The 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.