ffwebapps — Architecture Overview

This page is the system map for ffwebapps: the binaries, the shared library they all call, the Firefox runtime they drive, and the single socket that ties a running app to its tray and launcher.

Table of Contents

1. What ffwebapps is
2. The core idea: drive, don’t patch
3. Component model
4. The shared library
5. On-disk state
6. Lifecycle of an app
7. The one IPC boundary
8. Source layout
9. Design rules
10. Document index

1. What ffwebapps is

ffwebapps runs any website as a native, chromeless desktop app on Linux: its own window with no tabs or address bar, its own taskbar/dock identity, a system-tray icon with an unread badge, close-to-tray, and out-of-scope links that open in your real browser. It is a CLI-driven fork of PWAsForFirefox’s native component, re-architected to drive Firefox’s first-party Web Apps (Taskbar Tabs) feature rather than patch the browser chrome at runtime.

The whole project is one Rust crate (firefoxpwa) that produces several binaries plus a small bundle of privileged Firefox configuration. There is no long-lived ffwebapps daemon: the running app is a Firefox process, and everything else is either a one-shot CLI command or a thin client of the socket that Firefox process serves.

2. The core idea: drive, don’t patch

The upstream project, and most “site-specific browser” tools, achieve a chromeless window by patching the browser’s chrome at runtime — replacing browser.xhtml, injecting a custom UI, and maintaining that patch against every Firefox update. ffwebapps takes the opposite stance: it leans on a feature Mozilla now ships and maintains itself.

Firefox ≥ 151 includes Web Apps (Taskbar Tabs): pass firefox -taskbar-tab <id> and Firefox opens a standalone, minimal-UI window with its own Wayland app_id. ffwebapps' job is reduced to three things:

1. Register the app in the profile’s taskbartabs.json so the ID resolves to a scope and a start URL.
2. Configure the runtime through first-party mechanisms — a privileged _autoconfig.cfg, a profile user.js, and userChrome.css — to enable the feature, strip the last toolbar pixels, route links, and serve a tray socket.
3. Integrate with the desktop — generate the .desktop launcher, icons, and (on KDE) a window rule.

Nothing monkeypatches Firefox’s UI code. The chromeless look is userChrome.css; the behaviour is _autoconfig.cfg. Both are supported, documented Firefox extension points. See The Firefox Runtime & Autoconfig for the full mechanism.

3. Component model

ffwebapps is built from four binaries and one configuration bundle. Only the first three binaries matter for the Linux web-app flow; the connector is inherited from upstream.

The crucial property: there is no ffwebapps daemon. A web app that is “running” is a Firefox process. The CLI and GUI are short-lived; the tray is a thin remote that exits when its app does. State lives on disk and in that one Firefox process.

4. The shared library

Everything except the privileged JS lives in the firefoxpwa crate, and src/lib.rs re-exports each module so every binary calls the same code in-process:

pub mod components;   // Site, Profile, Runtime, taskbartabs registry
pub mod connector;    // inherited native-messaging protocol
pub mod console;      // clap command structs + the Run trait
pub mod directories;  // ProjectDirs — the on-disk layout
pub mod integrations; // .desktop / icons / autostart / KWin rules
pub mod storage;      // Storage + Config over config.json
pub mod utils;

The GTK GUI was deliberately built as a second binary in the same crate rather than a separate program. The core types (Site, Config, Storage, ProjectDirs, Profile) are #[non_exhaustive], which forbids construction from other crates but not from within this one — so the GUI can build command structs and call .run() directly, reusing manifest fetching, system integration, and storage writes instead of re-implementing or shelling out. See Data Model & Storage and CLI & Command Model.

5. On-disk state

A web app is fully described by files. There is no hidden runtime database; deleting the directories below removes the app.

Profiles are the unit of isolation: several apps can share one Firefox profile (and thus cookies, storage, and per-profile CSS/JS), or each can have its own. The Nil-ULID profile is the shared “Default”.

6. Lifecycle of an app

A single site install followed by a launch touches most of the system. The sequence makes the boundaries concrete:

1. Install (ffwebapps site install <MANIFEST_URL> --document-url <PAGE>): the library fetches the web-app manifest and icons, mints a ULID and a webapp_id (a UUID), writes the Site into config.json, generates the .desktop launcher and icons, and — on KDE — a kwinrulesrc position rule.
2. Launch (from the menu or site launch <ULID>): the console first probes the socket. If it connects, the app is already running, so it sends show and exits — the single-instance guarantee. Otherwise it writes taskbartabs.json and user.js, builds the Firefox argv, and spawns the runtime, optionally under a scheduling policy.
3. Run: Firefox loads _autoconfig.cfg, which binds the socket, takes ownership of the window’s hide/show, starts routing out-of-scope links, injects any per-app CSS/JS, and begins exporting the unread count.
4. Tray: the runtime (via the launch path) spawns ffwebapps-tray, which connects to the socket, draws the icon, and relays menu actions back as verbs.
5. Close to tray: the window’s X is intercepted and turned into a hide while a tray client is connected; otherwise it really closes. Quit (from the tray menu) sends quit, the runtime tears the socket down, and the tray sees EOF and exits.

7. The one IPC boundary

The entire live surface is a single Unix-domain socket, served by the Firefox runtime and consumed by thin clients. It uses a newline-delimited text protocol:

client -> runtime : hello v1 tray | hello v1 launcher
                    show | hide | toggle | quit | reload
                    mute-toggle | dnd-toggle | suspend-toggle
                    autostart-toggle | copy-url | open-browser
runtime -> client : hello v1 <pid>            (once, on connect)
                    unread <n>                (on change)
                    state hidden=… muted=… dnd=… suspend=… autostart=…

There are no pidfiles and no sentinel files: the runtime is alive if and only if the socket accepts a connection. That single invariant powers the singleton launcher, the tray’s liveness detection, and the GUI’s running/hidden status dot. The full protocol, the runtime-owned-window model, and the KWin hide/show mechanism are documented in IPC & the Runtime-Owned Window.

8. Source layout

9. Design rules

The architecture holds together because of a few deliberate choices, several of them learned the hard way (see the gotchas in each page):

• Drive Firefox’s first-party features; never patch its chrome. The chromeless look and all behaviour come from supported extension points.
• The runtime owns its window and lifecycle. Hide/show, close-to-tray, and quit are decided inside the Firefox process, not by an external window-manager script reaching in.
• One socket, one invariant. Liveness is “the socket accepts”; no pidfiles, no polling, no sentinels.
• The tray spawns nothing. It is a pure remote — zero Command::new calls — so it can never launch, relaunch, or strand a process.
• Config is files, owned by ffwebapps. A web app’s profile user.js and registry are managed by the library and regenerated at launch; nothing is hidden in opaque daemon state.
• Call the library in-process. The GUI reuses the CLI’s code paths rather than parsing CLI text or duplicating logic.

10. Document index