How berbicanes/apiark works
1. This is a multi-app monorepo centered on ApiArk, a local-first API client/platform. The main product is the desktop app, with supporting CLI, MCP server, VS Code extension, and a marketing/docs web app. Shared code lives in packages/.
2. Desktop app is the architectural core. It is built with Tauri v2: a React/TypeScript frontend in apps/desktop/src and a Rust backend in apps/desktop/src-tauri. The frontend renders the UI, manages app state, and calls backend commands through Tauri. The backend owns the heavy lifting: networking, parsing, storage, scripting, mock servers, proxying, and integrations.
3. Local-first file storage is a key boundary. The product stores collections, environments, settings, history, audit data, and state on the filesystem, with collections represented as YAML files and directories. That means the data model is intentionally Git-friendly and portable rather than database- or cloud-centric. Storage modules in src-tauri/src/storage encapsulate persistence and migration.
4. Request execution is split into request construction, transport, and response parsing. In the Rust backend, the http/ area contains interpolation, auth handling, curl parsing, request building, cookie handling, and response parsing. This is the core flow for REST-style requests, but the app also has dedicated protocol clients for other transports.
5. Multi-protocol support is a major subsystem. Separate backend modules handle gRPC, WebSocket, SSE, MQTT, Socket.IO, and GraphQL-related UI/interaction. These are not just UI tabs; they represent distinct transport/runtime paths and likely different request lifecycles and connection management.
6. Automation is first-class and runs locally. The runner/, scheduler/, and mock/ modules support collection execution, cron-like monitoring, and mock servers. The runner executes collections with data-driven inputs and produces results; the scheduler monitors those runs; the mock server exposes local endpoints derived from collections. These are important boundaries because they transform stored collection definitions into active services and reports.
7. Scripting and assertions are embedded in the request lifecycle. The Rust backend includes a scripting engine based on Deno/V8 (deno_core) and a custom ark_api.js bridge. This powers pre/post-request scripts, test assertions, and helper APIs exposed to users. That makes the request pipeline: load request → interpolate/env resolve → optional script/test hooks → send → parse → assert/report.
8. Import/export is a separate compatibility layer. The repo contains dedicated importers for Postman, Insomnia, Bruno, Hoppscotch, OpenAPI, HAR, and cURL, plus exporters for ApiArk, Bruno, Insomnia, OpenAPI, and Postman. This layer converts between external ecosystem formats and ApiArk’s internal YAML/file-based model, which is central to migration and interoperability.
9. Several auxiliary backend services sit alongside the request engine. There are modules for proxy capture (local intercepting HTTP/HTTPS proxy), OAuth flows/callbacks, terminal integration, history, audit, license, settings, and watcher support for filesystem changes. These are all local desktop capabilities managed by the backend and surfaced via Tauri commands.
10. Plugin and AI extensibility are explicit integration points. The backend has a plugins/ subsystem for JavaScript and WASM plugins, and an ai/ command surface in the desktop app for natural-language-assisted request generation and related workflows. These are extension boundaries rather than core storage or transport layers.
11. The frontend is organized by feature panels and persistent state stores. Under apps/desktop/src/components, the UI is broken into panels for collections, requests, responses, runner, history, proxy, mock, MQTT, WebSocket, SSE, GraphQL, gRPC, docs, settings, plugins, and more. Zustand stores in src/stores hold app-wide state such as collections, environments, tabs, console output, runner results, proxy state, and undo/history.
12. The CLI is a smaller Rust entry point for automation and import/export. apps/cli reuses the same domain concepts—collections, interpolation, import/export, reporting, and runner logic—to provide headless actions like running collections and importing files. It is packaged for npm via a thin JS wrapper, which makes distribution easier while keeping execution native.
13. The MCP server and VS Code extension extend ApiArk into AI/editor workflows. The MCP server (apps/mcp-server) exposes collection operations to MCP-compatible clients, while the VS Code extension (apps/vscode-extension) provides editor integration. These are separate entry points around the same collection-centric domain model rather than additional copies of the core engine.
14. The web app is mostly marketing and documentation, not runtime product logic. apps/web contains the public site, comparisons, download pages, docs pages, and a Remotion demo. It does not appear to participate in the desktop app’s execution path; it serves discovery, documentation, and conversion.
15. Build, packaging, and delivery are multi-channel. GitHub Actions handle CI, benchmarks, release, package-manager publishing, and nightly workflows. Packaging targets desktop installers plus Homebrew, Scoop, and APT. The repository is structured so the same product can be consumed as a desktop app, CLI, or developer-tool integrations, while sharing a common collection/data model.
Main entry points: src-tauri/src Desktop backend · types/src Shared types · cli/src CLI · importer Import/export
Components 19
Apps
User-facing entry points and experiences.
- MCP server · MCP-facing collection operations for external AI clients.
apps/mcp-server/src - CLI · Native command-line entry point for run, import, and reporting workflows.
apps/cli/src - VS Code ext · VS Code extension for editor workflow integration.
apps/vscode-extension/src
Desktop core
Tauri desktop app with React UI and Rust backend.
- Desktop UI · React/TypeScript interface, feature panels, stores, and Tauri command calls.
apps/desktop/src - Desktop backend · Rust command surface and orchestration layer for the desktop product.
apps/desktop/src-tauri/src
Local services
Backend subsystems that execute requests, automation, and integrations.
- Storage · Filesystem-backed collections, environments, settings, history, audit, and migration.
apps/desktop/src-tauri/src/storage - HTTP engine · Interpolation, auth, curl parsing, request building, cookies, and response parsing.
apps/desktop/src-tauri/src/http - Protocols · Dedicated runtime paths for gRPC, WebSocket, SSE, MQTT, Socket.IO, and GraphQL.
apps/desktop/src-tauri/src - Runner · Executes collections with data-driven inputs and produces results.
apps/desktop/src-tauri/src/runner - Scheduler · Cron-like monitoring and run supervision.
apps/desktop/src-tauri/src/scheduler - Mock server · Serves local endpoints derived from collections.
apps/desktop/src-tauri/src/mock - Scripting · Pre/post scripts, assertions, and Ark API bridge for request lifecycle automation.
apps/desktop/src-tauri/src/scripting - Import/export · Compatibility layer for Postman, Insomnia, Bruno, Hoppscotch, OpenAPI, HAR, and cURL.
apps/desktop/src-tauri/src/importer - Proxy capture · Local HTTP/HTTPS capture and certificate handling.
apps/desktop/src-tauri/src/proxy - Plugins · JavaScript and WASM plugin manager and execution boundary.
apps/desktop/src-tauri/src/plugins - OAuth · OAuth callbacks and authorization flow handling.
apps/desktop/src-tauri/src/oauth
Web
Marketing and documentation site.
- Web app · Marketing, docs, pricing, compare pages, and demo content.
apps/web/src/app
Shared packages
Reusable types and importer helpers.
- Shared types · Common TypeScript types and contracts reused across apps.
packages/types/src - Importer pkg · Shared importer helpers used by package consumers.
packages/importer/src
Connections 20
- Desktop UI → Desktop backend: Tauri commands · Frontend invokes Rust backend actions through Tauri.
- Desktop backend → Storage: persist · Backend reads and writes local-first filesystem data.
- Desktop backend → HTTP engine: build/send · Backend constructs and executes HTTP requests.
- Desktop backend → Protocols: protocol calls · Backend routes non-HTTP request lifecycles to protocol modules.
- Desktop backend → Runner: run collections · Backend executes collections and gathers results.
- Desktop backend → Scheduler: monitor runs · Backend schedules and monitors recurring executions.
- Desktop backend → Mock server: serve mocks · Backend exposes local mock endpoints derived from collections.
- Desktop backend → Scripting: scripts/assertions · Backend invokes script engine during request lifecycle.
- Desktop backend → Import/export: convert formats · Backend imports and exports external ecosystem formats.
- Desktop backend → Proxy capture: capture traffic · Backend manages local proxy capture.
- Desktop backend → Plugins: extend · Backend loads and manages plugins.
- Desktop backend → OAuth: authorize · Backend handles OAuth flows and callbacks.
- Desktop backend → Shared types: contracts · Desktop and other packages share domain types.
- CLI → Runner: run · CLI reuses collection execution logic for headless runs.
- CLI → Import/export: import/export · CLI exposes conversion workflows.
- CLI → Shared types: contracts · CLI shares core domain types.
- MCP server → Shared types: contracts · MCP server uses shared collection model types.
- VS Code ext → Shared types: contracts · Extension consumes shared domain types.
- Web app → Shared types: content models · Web app may reuse shared UI/domain definitions.
- Importer pkg → Import/export: helpers · Shared package supports import-related workflows.