How kbrdn1/lazycurl works
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: model.go App model · http.go HTTP engine · request_view.go Panels · import.go Import mode
Components 19
CLI Entry
Executable entrypoints for launching the app and import mode.
- Main app · Starts the interactive TUI workspace.
cmd/lazycurl/main.go - Import mode · Non-interactive import path in the same binary.
cmd/lazycurl/import.go
Interactive UI
Bubble Tea presentation, interaction, and screen components.
- App model · Top-level Bubble Tea model and state machine.
internal/ui/model.go - Panels · Request, response, collection, environment, console, and status views.
internal/ui/request_view.go - Widgets · Reusable dialogs, editors, tables, tabs, trees, search, and which-key overlays.
internal/ui/components/editor.go - Modes · Command input, jump mode, import modals, and keyboard-driven transitions.
internal/ui/mode.go - Messages · 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 · Builds and sends requests, then returns formatted responses.
internal/api/http.go - Collections · Request collections and item structure used by the UI.
internal/api/collection.go - Env & vars · Environment scoping, variable interpolation, and runtime value resolution.
internal/api/environment.go - Script runner · Executes pre-request and test scripts and coordinates script results.
internal/api/script_executor.go - Script API · Request, response, console, env, cookies, crypto, base64, info, and assertion helpers.
internal/api/script_request.go - External editor · 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 · Detects, parses, converts, and exports Postman collections and environments.
internal/import/postman/collection.go - Curl/OpenAPI · cURL parsing/generation and OpenAPI conversion into internal models.
internal/api/curl_parser.go
State & Config
Session persistence, runtime config, and shared styling.
- Formatter · Formats responses, payloads, and console output for display.
internal/format/formatter.go - Styles · Shared terminal styling for UI consistency.
pkg/styles/styles.go - Session · Persists and restores workspace/session state on disk.
internal/session/session.go - Config · Application settings that influence startup and behavior.
internal/config/config.go
Connections 21
- 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.