Architecture overview

Fetchpier separates the desktop shell from the business layer so the graphical app and fp CLI run the same workspace formats and request pipeline.

Desktop renderer (React UI)
        |
        | validated, narrow IPC bridge
        v
Electron main process ---------> @fetchpier/core
                                      ^
                                      |
fp command-line interface -----------+
                                      |
                                      v
                         workspace files + remote APIs

Desktop process boundary

The renderer is an operating-system-sandboxed Chromium process. It has no Node.js integration and cannot access the filesystem or network directly. A preload bridge exposes a deliberately small, typed set of operations. The Electron main process validates those calls, owns native dialogs and windows, and delegates workspace and request work to the core package.

This separation keeps renderer content away from arbitrary system calls. It also makes IPC contracts an explicit compatibility boundary: UI code receives serializable data rather than Node objects.

Shared business layer

@fetchpier/core owns operations that must behave identically in every client:

• workspace discovery, validation, initialization, and file layout;
• .http parsing and serialization;
• environment, local-value, secret, cookie, and TLS resolution;
• the HTTP pipeline, redirects, proxying, cancellation, and history records;
• schema import;
• the synchronous scripting sandbox and fp.* API.

The package accepts injected filesystem, transport, secret-key, and event adapters. Electron supplies desktop adapters; the CLI supplies terminal and process adapters. UI-only concerns such as tabs, dialogs, and visual state remain outside the core.

Command-line layer

@fetchpier/cli is a thin command and reporting layer over the core. It resolves command-line context, expands file and folder inputs, runs requests sequentially, renders CLI/JSON/JUnit/HTML reports, and maps outcomes to stable exit codes. It does not load Electron or a database.

The CLI and desktop share workspace data but not application-private state. In particular, the CLI cannot see app-global certificates or the desktop’s last selected environment.

Filesystem as the data model

There is no embedded database. Workspace files are the durable source of truth, with shared data kept separate from .state/ and .runs/ data that is ignored by default. Workspace writes use atomic replacement so an interruption leaves either the prior complete file or the new complete file.

The folder model provides compatibility with Git and other .http tools, while stable request and environment identifiers keep internal relationships attached across renames.

Network boundary

The main process and core perform connections that arise from a user request, a URL schema import, or the optional update check. The renderer is prevented from loading remote content by policy, navigation guards, tests, and build audits. See Privacy and network access for the user-visible contract.

Extension boundaries

Public extension points are intentionally limited:

• user-authored synchronous scripts use the documented fp.* API;
• automation uses the fp CLI or its programmatic API;
• workspace interoperability uses plain .http and JSON files.

Fetchpier does not currently expose a plugin system. Adding an IPC operation, core domain, body type, importer, setting, or CLI command is a product-development change that must preserve these process, filesystem, and network invariants.