# kbrdn1/lazycurl architecture

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

- Interactive diagram: https://gitdiagram.com/kbrdn1/lazycurl
- Repository: https://github.com/kbrdn1/lazycurl

## Overview

1. **Top-level shape**
   LazyCurl is a Go 1.21+ terminal application. The main executable lives in `cmd/lazycurl`, and the rest of the repository is split into small internal subsystems for UI, HTTP/script execution, import/export, configuration, and session persistence.

2. **Runtime entrypoints**
   `cmd/lazycurl/main.go` starts the interactive TUI app. `cmd/lazycurl/import.go` adds a non-interactive import path, so the same binary can either launch the workspace UI or convert external API definitions into LazyCurl’s internal collection model.

3. **Interactive UI layer**
   `internal/ui` is the presentation and interaction boundary. It contains the Bubble Tea-based application model, panel views, status bar, command input, modal dialogs, request/response panes, collection and environment browsers, jump mode, and keybinding/help overlays. This layer owns keyboard-driven state transitions and user-facing layout.

4. **Request/response flow**
   The UI’s request editor feeds into the HTTP execution path in `internal/api/http.go`. A request is assembled from the selected collection item, active environment variables, request body/headers, and any script mutations, then sent over the network. The response comes back through the same API boundary and is rendered in the response view after formatting.

5. **Scripting subsystem**
   `internal/api/script_*` and `internal/api/script_executor.go` implement the JavaScript automation layer. The repo exposes a structured scripting API for pre-request and test/post-request logic: request, response, console, environment, variables, cookies, info, crypto, base64, and assertion helpers. This is a major architectural boundary because scripts can mutate requests, inspect responses, and emit test results.

6. **Collections and environments**
   `internal/api/collection.go`, `environment.go`, and `variables.go` model the workspace data that users organize and edit in the UI. Collections hold requests; environments supply scoped variables that are interpolated with `{{var}}` syntax; variable helpers resolve runtime values across requests, scripts, and the UI.

7. **Import/export pipeline**
   `internal/import/postman` handles Postman collection and environment detection, parsing, conversion, and export. Separate API helpers handle cURL parsing/generation and OpenAPI conversion. In architecture terms, external formats flow through import adapters into the internal collection/environment model, rather than being edited directly in place.

8. **Workspace/session persistence**
   `internal/session` and the workspace concepts described in the README indicate that LazyCurl persists UI/workspace state on disk, typically under a `.lazycurl/` directory in the project. This is the boundary for restoring panels, selected items, and other session state across launches.

9. **External editor integration**
   `internal/api/external_editor.go` and the editor component in `internal/ui/components` provide the bridge to system editors like vim or VS Code. This lets the app hand off request bodies to an external process, then re-ingest the edited content back into the request state.

10. **Formatting and presentation utilities**
   `internal/format` and `pkg/styles` are supporting layers. The formatter shapes payloads, responses, and console output for display, while the shared styles package centralizes terminal styling so the UI remains consistent across panels and dialogs.

11. **Configuration and runtime behavior**
   `internal/config` governs app-level settings and likely wires preferences such as editor choice, workspace behavior, and UI customization. The configuration layer sits below the UI but above the core models, affecting both startup and runtime behavior.

12. **Tooling and delivery**
   The repo is built and released with Go-native tooling: CI in GitHub Actions, `goreleaser` for binaries, and pre-commit/golangci-lint for quality checks. The `docs/` and `wiki/` directories mirror the architecture in user-facing form, which is useful for validating diagram boundaries against intended behavior.

Main entry points: [`internal/ui/model.go`](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/model.go) (App model), [`internal/api/http.go`](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/http.go) (HTTP engine), [`internal/ui/request_view.go`](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/request_view.go) (Panels), [`cmd/lazycurl/import.go`](https://github.com/kbrdn1/lazycurl/blob/main/cmd/lazycurl/import.go) (Import mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI Entry"]
  node_node_main["Main app<br/>entrypoint<br/>[main.go]"]
  node_node_import_cmd["Import mode<br/>entrypoint<br/>[import.go]"]
end

subgraph group_group_ui["Interactive UI"]
  node_node_ui_model["App model<br/>tui state<br/>[model.go]"]
  node_node_ui_views["Panels<br/>ui views<br/>[request_view.go]"]
  node_node_ui_components["Widgets<br/>ui components<br/>[editor.go]"]
  node_node_ui_modes["Modes<br/>[mode.go]"]
  node_node_ui_messages["Messages<br/>ui events<br/>[messages.go]"]
end

subgraph group_group_core["Core API"]
  node_node_http["HTTP engine<br/>request execution<br/>[http.go]"]
  node_node_collection["Collections<br/>workspace model<br/>[collection.go]"]
  node_node_env_vars["Env & vars<br/>context model<br/>[environment.go]"]
  node_node_script_exec["Script runner<br/>js automation<br/>[script_executor.go]"]
  node_node_script_api["Script API<br/>js bindings<br/>[script_request.go]"]
  node_node_editor_bridge["External editor<br/>editor bridge<br/>[external_editor.go]"]
end

subgraph group_group_import["Import/Export"]
  node_node_postman["Postman import<br/>import adapter<br/>[collection.go]"]
  node_node_curl_openapi["Curl/OpenAPI<br/>import adapters<br/>[curl_parser.go]"]
end

subgraph group_group_state["State & Config"]
  node_node_formatter["Formatter<br/>presentation utils<br/>[formatter.go]"]
  node_node_styles["Styles<br/>theme utils<br/>[styles.go]"]
  node_node_session["Session<br/>workspace persistence<br/>[session.go]"]
  node_node_config["Config<br/>runtime settings<br/>[config.go]"]
end

node_node_main -->|"launches"| node_node_ui_model
node_node_import_cmd -->|"imports"| node_node_postman
node_node_import_cmd -->|"parses"| node_node_curl_openapi
node_node_ui_model -->|"renders"| node_node_ui_views
node_node_ui_model -->|"uses"| node_node_ui_components
node_node_ui_model -->|"transitions"| node_node_ui_modes
node_node_ui_model -->|"consumes"| node_node_ui_messages
node_node_ui_views -->|"sends request"| node_node_http
node_node_http -->|"reads"| node_node_collection
node_node_http -->|"resolves"| node_node_env_vars
node_node_http -->|"hooks scripts"| node_node_script_exec
node_node_script_exec -->|"exposes"| node_node_script_api
node_node_script_exec -->|"inspects response"| node_node_http
node_node_ui_views -->|"formats"| node_node_formatter
node_node_ui_components -->|"opens editor"| node_node_editor_bridge
node_node_ui_model -->|"restores"| node_node_session
node_node_ui_model -->|"applies"| node_node_config
node_node_ui_views -->|"themes"| node_node_styles
node_node_import_cmd -->|"converts to"| node_node_collection
node_node_postman -->|"maps"| node_node_collection
node_node_postman -->|"maps"| node_node_env_vars

click node_node_main "https://github.com/kbrdn1/lazycurl/blob/main/cmd/lazycurl/main.go"
click node_node_import_cmd "https://github.com/kbrdn1/lazycurl/blob/main/cmd/lazycurl/import.go"
click node_node_ui_model "https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/model.go"
click node_node_ui_views "https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/request_view.go"
click node_node_ui_components "https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/components/editor.go"
click node_node_ui_modes "https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/mode.go"
click node_node_ui_messages "https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/messages.go"
click node_node_http "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/http.go"
click node_node_collection "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/collection.go"
click node_node_env_vars "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/environment.go"
click node_node_script_exec "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/script_executor.go"
click node_node_script_api "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/script_request.go"
click node_node_editor_bridge "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/external_editor.go"
click node_node_formatter "https://github.com/kbrdn1/lazycurl/blob/main/internal/format/formatter.go"
click node_node_styles "https://github.com/kbrdn1/lazycurl/blob/main/pkg/styles/styles.go"
click node_node_session "https://github.com/kbrdn1/lazycurl/blob/main/internal/session/session.go"
click node_node_config "https://github.com/kbrdn1/lazycurl/blob/main/internal/config/config.go"
click node_node_postman "https://github.com/kbrdn1/lazycurl/blob/main/internal/import/postman/collection.go"
click node_node_curl_openapi "https://github.com/kbrdn1/lazycurl/blob/main/internal/api/curl_parser.go"

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_node_main,node_node_import_cmd toneBlue
class node_node_ui_model,node_node_ui_views,node_node_ui_components,node_node_ui_modes,node_node_ui_messages toneAmber
class node_node_http,node_node_collection,node_node_env_vars,node_node_script_exec,node_node_script_api,node_node_editor_bridge toneMint
class node_node_postman,node_node_curl_openapi toneRose
class node_node_formatter,node_node_styles,node_node_session,node_node_config toneIndigo
```

## Components

### CLI Entry

Executable entrypoints for launching the app and import mode.

- [Main app](https://github.com/kbrdn1/lazycurl/blob/main/cmd/lazycurl/main.go): entrypoint · Starts the interactive TUI workspace. · `cmd/lazycurl/main.go`
- [Import mode](https://github.com/kbrdn1/lazycurl/blob/main/cmd/lazycurl/import.go): entrypoint · Non-interactive import path in the same binary. · `cmd/lazycurl/import.go`

### Interactive UI

Bubble Tea presentation, interaction, and screen components.

- [App model](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/model.go): tui state · Top-level Bubble Tea model and state machine. · `internal/ui/model.go`
- [Panels](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/request_view.go): ui views · Request, response, collection, environment, console, and status views. · `internal/ui/request_view.go`
- [Widgets](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/components/editor.go): ui components · Reusable dialogs, editors, tables, tabs, trees, search, and which-key overlays. · `internal/ui/components/editor.go`
- [Modes](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/mode.go): interaction modes · Command input, jump mode, import modals, and keyboard-driven transitions. · `internal/ui/mode.go`
- [Messages](https://github.com/kbrdn1/lazycurl/blob/main/internal/ui/messages.go): ui events · Internal message flow for editor, console, and script state updates. · `internal/ui/messages.go`

### Core API

HTTP execution, scripting, workspace models, and editor bridges.

- [HTTP engine](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/http.go): request execution · Builds and sends requests, then returns formatted responses. · `internal/api/http.go`
- [Collections](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/collection.go): workspace model · Request collections and item structure used by the UI. · `internal/api/collection.go`
- [Env & vars](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/environment.go): context model · Environment scoping, variable interpolation, and runtime value resolution. · `internal/api/environment.go`
- [Script runner](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/script_executor.go): js automation · Executes pre-request and test scripts and coordinates script results. · `internal/api/script_executor.go`
- [Script API](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/script_request.go): js bindings · Request, response, console, env, cookies, crypto, base64, info, and assertion helpers. · `internal/api/script_request.go`
- [External editor](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/external_editor.go): editor bridge · Hands off content to system editors and re-ingests edited text. · `internal/api/external_editor.go`

### Import/Export

Adapters for external API formats and collection conversion.

- [Postman import](https://github.com/kbrdn1/lazycurl/blob/main/internal/import/postman/collection.go): import adapter · Detects, parses, converts, and exports Postman collections and environments. · `internal/import/postman/collection.go`
- [Curl/OpenAPI](https://github.com/kbrdn1/lazycurl/blob/main/internal/api/curl_parser.go): import adapters · cURL parsing/generation and OpenAPI conversion into internal models. · `internal/api/curl_parser.go`

### State & Config

Session persistence, runtime config, and shared styling.

- [Formatter](https://github.com/kbrdn1/lazycurl/blob/main/internal/format/formatter.go): presentation utils · Formats responses, payloads, and console output for display. · `internal/format/formatter.go`
- [Styles](https://github.com/kbrdn1/lazycurl/blob/main/pkg/styles/styles.go): theme utils · Shared terminal styling for UI consistency. · `pkg/styles/styles.go`
- [Session](https://github.com/kbrdn1/lazycurl/blob/main/internal/session/session.go): workspace persistence · Persists and restores workspace/session state on disk. · `internal/session/session.go`
- [Config](https://github.com/kbrdn1/lazycurl/blob/main/internal/config/config.go): runtime settings · Application settings that influence startup and behavior. · `internal/config/config.go`

## Connections

- Main app → App model: launches · The main executable starts the interactive workspace model.
- Import mode → Postman import: imports · Import mode routes external definitions into collection/environment conversion.
- Import mode → Curl/OpenAPI: parses · CLI import path can use cURL and OpenAPI adapters.
- App model → Panels: renders · The app model coordinates the major panels and screens.
- App model → Widgets: uses · Views are assembled from reusable UI widgets.
- App model → Modes: transitions · Keyboard-driven state changes are managed through modes.
- App model → Messages: consumes · Bubble Tea messages drive UI updates and side effects.
- Panels → HTTP engine: sends request · The request view feeds the execution boundary.
- HTTP engine → Collections: reads · Requests are assembled from collection items.
- HTTP engine → Env & vars: resolves · Active environment variables are interpolated into the request.
- HTTP engine → Script runner: hooks scripts · Request execution can be mutated and observed by scripts.
- Script runner → Script API: exposes · Script runner provides structured helpers and bindings.
- Script runner → HTTP engine: inspects response · Scripts can see the request/response cycle and emit results.
- Panels → Formatter: formats · Responses and console output are shaped for display.
- Widgets → External editor: opens editor · Editor widget hands off text to external editors.
- App model → Session: restores · Workspace state is loaded and saved across launches.
- App model → Config: applies · Runtime settings influence startup and UI behavior.
- Panels → Styles: themes · Panels and overlays share terminal styling.
- Import mode → Collections: converts to · Imported definitions end up in the internal collection model.
- Postman import → Collections: maps · Postman adapters convert external collections into LazyCurl structures.
- Postman import → Env & vars: maps · Environment files are converted into the internal variable model.
