# kong/insomnia architecture

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

- Interactive diagram: https://gitdiagram.com/kong/insomnia
- Repository: https://github.com/kong/insomnia

## Overview

Insomnia is a desktop API client for designing, sending, testing, and mocking APIs, with local, Git, or cloud-backed collaboration. The principal workflow is to create or import a project, configure a request and environment, send it over a supported protocol, inspect the response, and optionally run tests. The repository also includes the Inso CLI for specification lint/export and collection runs. The map preserves documented product branches; several feature implementations are unsampled, so their internal connections are omitted or marked unverified.

Main entry points: [`packages/insomnia-inso/src/cli.ts`](https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/cli.ts) (Inso CLI), [`packages/insomnia/src/common/collection.ts`](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/collection.ts) (Request authoring), [`packages/insomnia-data/node-src/database/database-nedb.ts`](https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/database/database-nedb.ts) (Local database), [`packages/insomnia/src/routes.ts`](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/routes.ts) (Insomnia desktop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["API Client"]
  node_desktop["Insomnia desktop<br/>[routes.ts]"]
  node_request["Request authoring<br/>[collection.ts]"]
  node_transport["Protocol debugging"]
  node_response["Response inspection<br/>[response.ts]"]
  node_templating["Template rendering<br/>[liquid-engine.ts]"]
  node_scripting["Script execution"]
end

subgraph group_design["Design and Testing"]
  node_api_design["API design<br/>[api-specs.ts]"]
  node_test_runner["Collection testing<br/>[run.ts]"]
  node_mocking["API mocking<br/>[mock-server.ts]"]
end

subgraph group_storage["Data and Collaboration"]
  node_data_models["Resource models<br/>[db-models.ts]"]
  node_database[("Local database<br/>[database-nedb.ts]")]
  node_project_service["Project service<br/>[project.ts]"]
  node_git_sync["Git sync<br/>[vcs.ts]"]
  node_cloud_collab["Cloud collaboration<br/>[project.ts]"]
  node_local_storage[("App local storage")]
end

subgraph group_cli["Inso CLI"]
  node_inso_cli["Inso CLI<br/>[cli.ts]"]
  node_cli_db["CLI data access<br/>[index.ts]"]
  node_spec_lint["Specification lint"]
  node_spec_export["Specification export"]
  node_run_report["Run reporting<br/>[result-report.ts]"]
end

subgraph group_integrations["Extensions and Services"]
  node_plugins["Plugin extensions<br/>[types.ts]"]
  node_api_service["Insomnia account API<br/>[fetch.ts]"]
end

node_user(("API developer"))

node_user -->|"uses"| node_desktop
node_desktop -.->|"authors"| node_request
node_request -.->|"sends requests"| node_transport
node_transport -.->|"produces response"| node_response
node_request -.->|"renders values"| node_templating
node_request -.->|"runs scripts"| node_scripting
node_user -->|"designs APIs"| node_api_design
node_user -->|"tests collections"| node_test_runner
node_user -->|"mocks APIs"| node_mocking
node_user -->|"runs CI"| node_inso_cli
node_inso_cli -->|"loads data"| node_cli_db
node_inso_cli -->|"invokes lint"| node_spec_lint
node_inso_cli -->|"exports specs"| node_spec_export
node_inso_cli -->|"updates report"| node_run_report
node_database -->|"repairs projects"| node_project_service
node_database -->|"validates documents"| node_data_models
node_user -->|"chooses storage"| node_git_sync
node_user -->|"collaborates"| node_cloud_collab
node_user -->|"chooses storage"| node_local_storage
node_plugins -->|"adds tags"| node_templating
node_api_service -.->|"supports collaboration"| node_cloud_collab

click node_desktop "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/routes.ts"
click node_request "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/collection.ts"
click node_transport "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/network/send-action-runtime.ts"
click node_response "https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/src/models/response.ts"
click node_templating "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/templating/liquid-engine.ts"
click node_scripting "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/scripting/quickjs-script-engine.ts"
click node_api_design "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/api-specs.ts"
click node_test_runner "https://github.com/kong/insomnia/blob/develop/packages/insomnia-testing/src/run/run.ts"
click node_mocking "https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/services/mock-server.ts"
click node_data_models "https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/src/models/db-models.ts"
click node_database "https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/database/database-nedb.ts"
click node_project_service "https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/services/project.ts"
click node_git_sync "https://github.com/kong/insomnia/blob/develop/packages/insomnia-vcs/src/vcs.ts"
click node_cloud_collab "https://github.com/kong/insomnia/blob/develop/packages/insomnia-api/src/project.ts"
click node_local_storage "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/main/electron-storage.ts"
click node_inso_cli "https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/cli.ts"
click node_cli_db "https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/db/index.ts"
click node_spec_lint "https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/commands/lint-specification.ts"
click node_spec_export "https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/commands/export-specification.ts"
click node_run_report "https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/commands/run-collection/result-report.ts"
click node_plugins "https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/plugins/types.ts"
click node_api_service "https://github.com/kong/insomnia/blob/develop/packages/insomnia-api/src/fetch.ts"

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_desktop,node_request,node_transport,node_response,node_templating,node_scripting toneBlue
class node_api_design,node_test_runner,node_mocking toneAmber
class node_data_models,node_database,node_project_service,node_git_sync,node_cloud_collab,node_local_storage,node_user toneMint
class node_inso_cli,node_cli_db,node_spec_lint,node_spec_export,node_run_report toneRose
class node_plugins,node_api_service toneIndigo
```

## Components

### API Client

- [Insomnia desktop](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/routes.ts): `packages/insomnia/src/routes.ts`
- [Request authoring](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/collection.ts): `packages/insomnia/src/common/collection.ts`
- [Protocol debugging](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/network/send-action-runtime.ts): `packages/insomnia/src/common/network/send-action-runtime.ts`
- [Response inspection](https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/src/models/response.ts): `packages/insomnia-data/src/models/response.ts`
- [Template rendering](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/templating/liquid-engine.ts): `packages/insomnia/src/common/templating/liquid-engine.ts`
- [Script execution](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/scripting/quickjs-script-engine.ts): `packages/insomnia/src/scripting/quickjs-script-engine.ts`

### Design and Testing

- [API design](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/api-specs.ts): `packages/insomnia/src/common/api-specs.ts`
- [Collection testing](https://github.com/kong/insomnia/blob/develop/packages/insomnia-testing/src/run/run.ts): `packages/insomnia-testing/src/run/run.ts`
- [API mocking](https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/services/mock-server.ts): `packages/insomnia-data/node-src/services/mock-server.ts`

### Data and Collaboration

- [Resource models](https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/src/models/db-models.ts): `packages/insomnia-data/src/models/db-models.ts`
- [Local database](https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/database/database-nedb.ts): `packages/insomnia-data/node-src/database/database-nedb.ts`
- [Project service](https://github.com/kong/insomnia/blob/develop/packages/insomnia-data/node-src/services/project.ts): `packages/insomnia-data/node-src/services/project.ts`
- [Git sync](https://github.com/kong/insomnia/blob/develop/packages/insomnia-vcs/src/vcs.ts): `packages/insomnia-vcs/src/vcs.ts`
- [Cloud collaboration](https://github.com/kong/insomnia/blob/develop/packages/insomnia-api/src/project.ts): `packages/insomnia-api/src/project.ts`
- [App local storage](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/main/electron-storage.ts): `packages/insomnia/src/main/electron-storage.ts`

### Inso CLI

- [Inso CLI](https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/cli.ts): `packages/insomnia-inso/src/cli.ts`
- [CLI data access](https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/db/index.ts): `packages/insomnia-inso/src/db/index.ts`
- [Specification lint](https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/commands/lint-specification.ts): `packages/insomnia-inso/src/commands/lint-specification.ts`
- [Specification export](https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/commands/export-specification.ts): `packages/insomnia-inso/src/commands/export-specification.ts`
- [Run reporting](https://github.com/kong/insomnia/blob/develop/packages/insomnia-inso/src/commands/run-collection/result-report.ts): `packages/insomnia-inso/src/commands/run-collection/result-report.ts`

### Extensions and Services

- [Plugin extensions](https://github.com/kong/insomnia/blob/develop/packages/insomnia/src/common/plugins/types.ts): `packages/insomnia/src/common/plugins/types.ts`
- [Insomnia account API](https://github.com/kong/insomnia/blob/develop/packages/insomnia-api/src/fetch.ts): `packages/insomnia-api/src/fetch.ts`

### Other components

- **API developer**

## Connections

- API developer → Insomnia desktop: uses (evidence: `README.md`)
- Insomnia desktop → Request authoring: authors
- Request authoring → Protocol debugging: sends requests
- Protocol debugging → Response inspection: produces response
- Request authoring → Template rendering: renders values
- Request authoring → Script execution: runs scripts
- API developer → API design: designs APIs (evidence: `README.md`)
- API developer → Collection testing: tests collections (evidence: `README.md`)
- API developer → API mocking: mocks APIs (evidence: `README.md`)
- API developer → Inso CLI: runs CI (evidence: `README.md`)
- Inso CLI → CLI data access: loads data (evidence: `packages/insomnia-inso/src/cli.ts`)
- Inso CLI → Specification lint: invokes lint (evidence: `packages/insomnia-inso/src/cli.ts`)
- Inso CLI → Specification export: exports specs (evidence: `packages/insomnia-inso/src/cli.ts`)
- Inso CLI → Run reporting: updates report (evidence: `packages/insomnia-inso/src/cli.ts`)
- Local database → Project service: repairs projects
- Local database → Resource models: validates documents (evidence: `packages/insomnia-data/node-src/database/database-nedb.ts`)
- API developer → Git sync: chooses storage (evidence: `README.md`)
- API developer → Cloud collaboration: collaborates (evidence: `README.md`)
- API developer → App local storage: chooses storage (evidence: `README.md`)
- Plugin extensions → Template rendering: adds tags (evidence: `packages/insomnia/src/common/templating/liquid-engine.ts`)
- Insomnia account API → Cloud collaboration: supports collaboration
