# berbicanes/apiark architecture

> Architecture diagram of the GitHub repository berbicanes/apiark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/berbicanes/apiark
- Repository: https://github.com/berbicanes/apiark

## Overview

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: [`apps/desktop/src-tauri/src`](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src) (Desktop backend), [`packages/types/src`](https://github.com/berbicanes/apiark/tree/main/packages/types/src) (Shared types), [`apps/cli/src`](https://github.com/berbicanes/apiark/tree/main/apps/cli/src) (CLI), [`apps/desktop/src-tauri/src/importer`](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/importer) (Import/export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_mcp_server["MCP server<br/>automation endpoint"]
  node_cli["CLI<br/>headless rust app"]
  node_vscode_ext["VS Code ext<br/>editor integration"]
end

subgraph group_desktop_core["Desktop core"]
  node_desktop_ui["Desktop UI<br/>react frontend"]
  node_desktop_backend["Desktop backend<br/>tauri rust backend"]
end

subgraph group_services["Local services"]
  node_storage[("Storage<br/>local-first persistence")]
  node_http_engine["HTTP engine<br/>request pipeline"]
  node_protocols["Protocols<br/>multi-protocol runtimes"]
  node_runner["Runner<br/>collection execution"]
  node_scheduler["Scheduler<br/>monitoring"]
  node_mock["Mock server<br/>local endpoint server"]
  node_scripting["Scripting<br/>deno/v8 runtime"]
  node_import_export["Import/export<br/>format bridge"]
  node_proxy["Proxy capture<br/>intercepting proxy"]
  node_plugins["Plugins<br/>extensibility"]
  node_oauth["OAuth<br/>auth flow"]
end

subgraph group_web["Web"]
  node_web_app["Web app<br/>next.js site"]
end

subgraph group_shared["Shared packages"]
  node_shared_types["Shared types<br/>ts package"]
  node_shared_importer["Importer pkg<br/>ts package"]
end

node_desktop_ui -->|"Tauri commands"| node_desktop_backend
node_desktop_backend -->|"persist"| node_storage
node_desktop_backend -->|"build/send"| node_http_engine
node_desktop_backend -->|"protocol calls"| node_protocols
node_desktop_backend -->|"run collections"| node_runner
node_desktop_backend -->|"monitor runs"| node_scheduler
node_desktop_backend -->|"serve mocks"| node_mock
node_desktop_backend -->|"scripts/assertions"| node_scripting
node_desktop_backend -->|"convert formats"| node_import_export
node_desktop_backend -->|"capture traffic"| node_proxy
node_desktop_backend -->|"extend"| node_plugins
node_desktop_backend -->|"authorize"| node_oauth
node_desktop_backend -->|"contracts"| node_shared_types
node_cli -->|"run"| node_runner
node_cli -->|"import/export"| node_import_export
node_cli -->|"contracts"| node_shared_types
node_mcp_server -->|"contracts"| node_shared_types
node_vscode_ext -->|"contracts"| node_shared_types
node_web_app -.->|"content models"| node_shared_types
node_shared_importer -.->|"helpers"| node_import_export

click node_desktop_ui "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src"
click node_desktop_backend "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src"
click node_storage "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/storage"
click node_http_engine "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/http"
click node_protocols "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src"
click node_runner "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/runner"
click node_scheduler "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/scheduler"
click node_mock "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/mock"
click node_scripting "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/scripting"
click node_import_export "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/importer"
click node_proxy "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/proxy"
click node_plugins "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/plugins"
click node_oauth "https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/oauth"
click node_mcp_server "https://github.com/berbicanes/apiark/tree/main/apps/mcp-server/src"
click node_cli "https://github.com/berbicanes/apiark/tree/main/apps/cli/src"
click node_vscode_ext "https://github.com/berbicanes/apiark/tree/main/apps/vscode-extension/src"
click node_web_app "https://github.com/berbicanes/apiark/tree/main/apps/web/src/app"
click node_shared_types "https://github.com/berbicanes/apiark/tree/main/packages/types/src"
click node_shared_importer "https://github.com/berbicanes/apiark/tree/main/packages/importer/src"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_server,node_cli,node_vscode_ext toneBlue
class node_desktop_ui,node_desktop_backend toneAmber
class node_storage,node_http_engine,node_protocols,node_runner,node_scheduler,node_mock,node_scripting,node_import_export,node_proxy,node_plugins,node_oauth toneMint
class node_web_app toneRose
class node_shared_types,node_shared_importer toneIndigo
```

## Components

### Apps

User-facing entry points and experiences.

- [MCP server](https://github.com/berbicanes/apiark/tree/main/apps/mcp-server/src): automation endpoint · MCP-facing collection operations for external AI clients. · `apps/mcp-server/src`
- [CLI](https://github.com/berbicanes/apiark/tree/main/apps/cli/src): headless rust app · Native command-line entry point for run, import, and reporting workflows. · `apps/cli/src`
- [VS Code ext](https://github.com/berbicanes/apiark/tree/main/apps/vscode-extension/src): editor integration · VS Code extension for editor workflow integration. · `apps/vscode-extension/src`

### Desktop core

Tauri desktop app with React UI and Rust backend.

- [Desktop UI](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src): react frontend · React/TypeScript interface, feature panels, stores, and Tauri command calls. · `apps/desktop/src`
- [Desktop backend](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src): tauri rust 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](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/storage): local-first persistence · Filesystem-backed collections, environments, settings, history, audit, and migration. · `apps/desktop/src-tauri/src/storage`
- [HTTP engine](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/http): request pipeline · Interpolation, auth, curl parsing, request building, cookies, and response parsing. · `apps/desktop/src-tauri/src/http`
- [Protocols](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src): multi-protocol runtimes · Dedicated runtime paths for gRPC, WebSocket, SSE, MQTT, Socket.IO, and GraphQL. · `apps/desktop/src-tauri/src`
- [Runner](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/runner): collection execution · Executes collections with data-driven inputs and produces results. · `apps/desktop/src-tauri/src/runner`
- [Scheduler](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/scheduler): monitoring · Cron-like monitoring and run supervision. · `apps/desktop/src-tauri/src/scheduler`
- [Mock server](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/mock): local endpoint server · Serves local endpoints derived from collections. · `apps/desktop/src-tauri/src/mock`
- [Scripting](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/scripting): deno/v8 runtime · Pre/post scripts, assertions, and Ark API bridge for request lifecycle automation. · `apps/desktop/src-tauri/src/scripting`
- [Import/export](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/importer): format bridge · Compatibility layer for Postman, Insomnia, Bruno, Hoppscotch, OpenAPI, HAR, and cURL. · `apps/desktop/src-tauri/src/importer`
- [Proxy capture](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/proxy): intercepting proxy · Local HTTP/HTTPS capture and certificate handling. · `apps/desktop/src-tauri/src/proxy`
- [Plugins](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/plugins): extensibility · JavaScript and WASM plugin manager and execution boundary. · `apps/desktop/src-tauri/src/plugins`
- [OAuth](https://github.com/berbicanes/apiark/tree/main/apps/desktop/src-tauri/src/oauth): auth flow · OAuth callbacks and authorization flow handling. · `apps/desktop/src-tauri/src/oauth`

### Web

Marketing and documentation site.

- [Web app](https://github.com/berbicanes/apiark/tree/main/apps/web/src/app): next.js site · Marketing, docs, pricing, compare pages, and demo content. · `apps/web/src/app`

### Shared packages

Reusable types and importer helpers.

- [Shared types](https://github.com/berbicanes/apiark/tree/main/packages/types/src): ts package · Common TypeScript types and contracts reused across apps. · `packages/types/src`
- [Importer pkg](https://github.com/berbicanes/apiark/tree/main/packages/importer/src): ts package · Shared importer helpers used by package consumers. · `packages/importer/src`

## Connections

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