# usebruno/bruno architecture

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

- Interactive diagram: https://gitdiagram.com/usebruno/bruno
- Repository: https://github.com/usebruno/bruno
- Video tour (about a minute): https://gitdiagram.com/usebruno/bruno/video

## Overview

Bruno is an offline API client whose collections are stored as plain-text Bru files and can be version-controlled locally. The desktop workflow is to open a collection, configure requests and environments, execute requests, and inspect results; the CLI can run collections too. The map also preserves documented conversion, mock-server, and protocol capabilities visible in the repository tree. Some central Electron request-preparation and collection-watching modules are named by the source index but not present in the supplied tree, so their links are left unverified rather than asserted as observed calls.

Main entry points: [`packages/bruno-app/src/pages/Main.js`](https://github.com/usebruno/bruno/blob/main/packages/bruno-app/src/pages/Main.js) (Desktop workspace), [`packages/bruno-electron/src/ipc/network`](https://github.com/usebruno/bruno/tree/main/packages/bruno-electron/src/ipc/network) (Request preparation), [`packages/bruno-electron/src/app/collection-watcher.js`](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/app/collection-watcher.js) (Collection watcher), [`packages/bruno-electron/src/ipc/network/grpc-event-handlers.js`](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/ipc/network/grpc-event-handlers.js) (gRPC handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Desktop workspace<br/>[Main.js]"]
  node_request_ui["Request editor"]
  node_environment_ui["Environment settings"]
  node_ai_ui["AI assistant"]
end

subgraph group_collection["Collections and data"]
  node_collection_watcher["Collection watcher"]
  node_filestore["Collection formats<br/>[worker-script.ts]"]
  node_collection_io["Collection I/O<br/>[index.ts]"]
  node_conversion["Collection converters"]
end

subgraph group_execution["Request execution"]
  node_request_prep["Request preparation"]
  node_http_runtime["HTTP request runtime"]
  node_grpc_handlers["gRPC handlers"]
  node_grpc_client["gRPC client<br/>[grpc-client.js]"]
  node_ws_handlers["WebSocket handlers"]
  node_ws_client["WebSocket client<br/>[ws-client.js]"]
  node_oauth_callback["OAuth callback"]
end

subgraph group_integrations["API tooling"]
  node_mock_server["Mock server"]
  node_api_docs["API documentation<br/>[index.ts]"]
end

subgraph group_automation["Automation"]
  node_cli["Collection CLI<br/>[run.js]"]
  node_git["Local version control"]
end

node_user(("API developer"))

node_user -->|"uses"| node_app
node_app -.->|"edits requests"| node_request_ui
node_app -.->|"configures environments"| node_environment_ui
node_app -.->|"opens collections"| node_collection_watcher
node_collection_watcher -->|"parses files"| node_filestore
node_user -->|"runs collections"| node_cli
node_cli -.->|"loads collection"| node_collection_watcher
node_request_ui -.->|"submits request"| node_request_prep
node_request_prep -.->|"dispatches HTTP"| node_http_runtime
node_grpc_handlers -->|"calls gRPC"| node_grpc_client
node_ws_handlers -->|"calls WebSocket"| node_ws_client
node_grpc_handlers -.->|"prepares request"| node_request_prep
node_ws_handlers -.->|"prepares request"| node_request_prep
node_oauth_callback -.->|"returns authorization"| node_user
node_user -.->|"imports API definitions"| node_conversion
node_user -.->|"uses mock APIs"| node_mock_server
node_user -.->|"explores API docs"| node_api_docs
node_collection_io -.->|"writes collection"| node_filestore
node_user -->|"versions collections"| node_git
node_ai_ui -.->|"assists workflow"| node_app

click node_app "https://github.com/usebruno/bruno/blob/main/packages/bruno-app/src/pages/Main.js"
click node_request_ui "https://github.com/usebruno/bruno/tree/main/packages/bruno-app/src/components/RequestPane"
click node_environment_ui "https://github.com/usebruno/bruno/tree/main/packages/bruno-app/src/components/Environments"
click node_ai_ui "https://github.com/usebruno/bruno/tree/main/packages/bruno-app/src/components/AiChatSidebar"
click node_collection_watcher "https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/app/collection-watcher.js"
click node_filestore "https://github.com/usebruno/bruno/blob/main/packages/bruno-filestore/src/workers/worker-script.ts"
click node_collection_io "https://github.com/usebruno/bruno/blob/main/packages/bruno-io/src/writeCollection/index.ts"
click node_conversion "https://github.com/usebruno/bruno/blob/main/packages/bruno-converters/src/openapi/openapi-to-bruno.js"
click node_request_prep "https://github.com/usebruno/bruno/tree/main/packages/bruno-electron/src/ipc/network"
click node_http_runtime "https://github.com/usebruno/bruno/tree/main/packages/bruno-requests/src"
click node_grpc_handlers "https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/ipc/network/grpc-event-handlers.js"
click node_grpc_client "https://github.com/usebruno/bruno/blob/main/packages/bruno-requests/src/grpc/grpc-client.js"
click node_ws_handlers "https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/ipc/network/ws-event-handlers.js"
click node_ws_client "https://github.com/usebruno/bruno/blob/main/packages/bruno-requests/src/ws/ws-client.js"
click node_oauth_callback "https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/utils/oauth2-protocol-handler.js"
click node_mock_server "https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/app/mock-server/mock-response-routes.js"
click node_api_docs "https://github.com/usebruno/bruno/blob/main/packages/bruno-common/src/api-docs/index.ts"
click node_cli "https://github.com/usebruno/bruno/blob/main/packages/bruno-cli/src/commands/run.js"

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_app,node_request_ui,node_environment_ui,node_ai_ui toneBlue
class node_collection_watcher,node_filestore,node_collection_io,node_conversion toneAmber
class node_request_prep,node_http_runtime,node_grpc_handlers,node_grpc_client,node_ws_handlers,node_ws_client,node_oauth_callback,node_user toneMint
class node_mock_server,node_api_docs toneRose
class node_cli,node_git toneIndigo
```

## Components

### Client experience

- [Desktop workspace](https://github.com/usebruno/bruno/blob/main/packages/bruno-app/src/pages/Main.js): `packages/bruno-app/src/pages/Main.js`
- [Request editor](https://github.com/usebruno/bruno/tree/main/packages/bruno-app/src/components/RequestPane): `packages/bruno-app/src/components/RequestPane`
- [Environment settings](https://github.com/usebruno/bruno/tree/main/packages/bruno-app/src/components/Environments): `packages/bruno-app/src/components/Environments`
- [AI assistant](https://github.com/usebruno/bruno/tree/main/packages/bruno-app/src/components/AiChatSidebar): `packages/bruno-app/src/components/AiChatSidebar`

### Collections and data

- [Collection watcher](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/app/collection-watcher.js): `packages/bruno-electron/src/app/collection-watcher.js`
- [Collection formats](https://github.com/usebruno/bruno/blob/main/packages/bruno-filestore/src/workers/worker-script.ts): `packages/bruno-filestore/src/workers/worker-script.ts`
- [Collection I/O](https://github.com/usebruno/bruno/blob/main/packages/bruno-io/src/writeCollection/index.ts): `packages/bruno-io/src/writeCollection/index.ts`
- [Collection converters](https://github.com/usebruno/bruno/blob/main/packages/bruno-converters/src/openapi/openapi-to-bruno.js): `packages/bruno-converters/src/openapi/openapi-to-bruno.js`

### Request execution

- [Request preparation](https://github.com/usebruno/bruno/tree/main/packages/bruno-electron/src/ipc/network): `packages/bruno-electron/src/ipc/network`
- [HTTP request runtime](https://github.com/usebruno/bruno/tree/main/packages/bruno-requests/src): `packages/bruno-requests/src`
- [gRPC handlers](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/ipc/network/grpc-event-handlers.js): `packages/bruno-electron/src/ipc/network/grpc-event-handlers.js`
- [gRPC client](https://github.com/usebruno/bruno/blob/main/packages/bruno-requests/src/grpc/grpc-client.js): `packages/bruno-requests/src/grpc/grpc-client.js`
- [WebSocket handlers](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/ipc/network/ws-event-handlers.js): `packages/bruno-electron/src/ipc/network/ws-event-handlers.js`
- [WebSocket client](https://github.com/usebruno/bruno/blob/main/packages/bruno-requests/src/ws/ws-client.js): `packages/bruno-requests/src/ws/ws-client.js`
- [OAuth callback](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/utils/oauth2-protocol-handler.js): `packages/bruno-electron/src/utils/oauth2-protocol-handler.js`

### API tooling

- [Mock server](https://github.com/usebruno/bruno/blob/main/packages/bruno-electron/src/app/mock-server/mock-response-routes.js): `packages/bruno-electron/src/app/mock-server/mock-response-routes.js`
- [API documentation](https://github.com/usebruno/bruno/blob/main/packages/bruno-common/src/api-docs/index.ts): `packages/bruno-common/src/api-docs/index.ts`

### Automation

- [Collection CLI](https://github.com/usebruno/bruno/blob/main/packages/bruno-cli/src/commands/run.js): `packages/bruno-cli/src/commands/run.js`
- **Local version control**

### Other components

- **API developer**

## Connections

- API developer → Desktop workspace: uses
- Desktop workspace → Request editor: edits requests
- Desktop workspace → Environment settings: configures environments
- Desktop workspace → Collection watcher: opens collections
- Collection watcher → Collection formats: parses files (evidence: `packages/bruno-electron/src/app/collection-watcher.js`)
- API developer → Collection CLI: runs collections
- Collection CLI → Collection watcher: loads collection
- Request editor → Request preparation: submits request
- Request preparation → HTTP request runtime: dispatches HTTP
- gRPC handlers → gRPC client: calls gRPC (evidence: `packages/bruno-electron/src/ipc/network/grpc-event-handlers.js`)
- WebSocket handlers → WebSocket client: calls WebSocket (evidence: `packages/bruno-electron/src/ipc/network/ws-event-handlers.js`)
- gRPC handlers → Request preparation: prepares request (evidence: `packages/bruno-electron/src/ipc/network/grpc-event-handlers.js`)
- WebSocket handlers → Request preparation: prepares request (evidence: `packages/bruno-electron/src/ipc/network/ws-event-handlers.js`)
- OAuth callback → API developer: returns authorization
- API developer → Collection converters: imports API definitions
- API developer → Mock server: uses mock APIs
- API developer → API documentation: explores API docs
- Collection I/O → Collection formats: writes collection
- API developer → Local version control: versions collections
- AI assistant → Desktop workspace: assists workflow
