How darrenburns/posting works
Purpose and Entry Points
Posting is a local, keyboard-driven terminal UI HTTP client. It creates, runs, imports, exports, and persists HTTP requests as YAML-backed collections. The CLI module starts the application: src/posting/__main__.py, src/posting/app.py, src/posting/version.py.
TUI Application Shell
The Textual-based application owns screen composition, lifecycle, commands, and cross-widget messaging. It coordinates request editing, collection navigation, response display, help, themes, and overlays rather than exposing a web or server runtime. Core paths: src/posting/app.py, src/posting/commands.py, src/posting/messages.py.
Request Collections and Local Persistence
Requests are durable local YAML documents organized into collection directories. Collection/file services load, enumerate, save, and locate request definitions; the collection browser and save flow operate at this boundary. Core paths: src/posting/collection.py, src/posting/files.py, src/posting/save_request.py.
Request Authoring Pipeline
The request editor composes method, URL/path, query parameters, headers, authentication, body, options, metadata, and request scripts. Its output is the editable request model passed to execution and persistence. Core paths: src/posting/widgets/request/request_editor.py, src/posting/widgets/request/request_auth.py, src/posting/request_headers.py.
Execution, Authentication, and Response Rendering
HTTP execution is initiated from the app/editor flow, with auth construction separated from UI concerns. Returned status, headers, cookies, body, trace data, and script output are rendered through dedicated response views. Core paths: src/posting/app.py, src/posting/auth.py, src/posting/widgets/response/response_area.py.
Environments, Variables, and Scripts
Environment files and variable resolution supply reusable values to request fields, with autocomplete/input widgets exposing them in the UI. User Python scripts can run around requests, creating a controlled extension boundary between local request data and execution behavior. Core paths: src/posting/variables.py, src/posting/scripts.py, src/posting/widgets/variable_autocomplete.py.
Import/Export and Interoperability
Import adapters translate pasted cURL, Postman collections, and OpenAPI specifications into Posting’s collection/request representation. cURL export provides the reverse interoperability path for individual requests. Core paths: src/posting/importing/curl.py, src/posting/importing/postman.py, src/posting/importing/open_api.py.
Runtime and External Boundaries
The material runtime is Python (project metadata in pyproject.toml) with Textual for terminal UI behavior. Requests target arbitrary user-selected HTTP services; no repository-owned backend is indicated. Tree-sitter-based highlighting, terminal editor/pager integration, YAML files, environment files, and user Python scripts are external/local-system boundaries. Core paths: pyproject.toml, src/posting/highlighters.py, src/posting/yaml.py.
Main entry points: app.py Application shell · request_editor.py Request editor · collection.py Collections · response_area.py Response views
Components 20
Terminal UI
Textual application and interactive views.
- Application shell · Owns lifecycle, screens, commands, and cross-widget messaging.
src/posting/app.py - Commands & messages
src/posting/commands.py - Request editor · Builds the editable HTTP request model.
src/posting/widgets/request/request_editor.py - Auth editor
src/posting/widgets/request/request_auth.py - Response views · Renders status, headers, cookies, body, traces, and script output.
src/posting/widgets/response/response_area.py - Syntax highlighting
src/posting/highlighters.py - Variable autocomplete
src/posting/widgets/variable_autocomplete.py
Local request data
YAML-backed collections, environments, and scripts.
- Collections · Loads, enumerates, saves, and locates request definitions.
src/posting/collection.py - Collection files
src/posting/files.py - Save flow
src/posting/save_request.py - YAML documents · Durable request collections and environment files.
src/posting/yaml.py - Variables & environments · Resolves reusable environment values for request fields.
src/posting/variables.py - User scripts · Runs user Python around request execution.
src/posting/scripts.py
Interoperability
Request format translation at the application boundary.
- cURL import/export
src/posting/importing/curl.py - Postman import
src/posting/importing/postman.py - OpenAPI import
src/posting/importing/open_api.py
Other components
- CLI entry point
src/posting/__main__.py - Authentication builder
src/posting/auth.py - User-selected HTTP service · Arbitrary remote endpoint selected by the user.
- Python + Textual runtime
pyproject.toml
Connections 24
- CLI entry point → Application shell: starts
- Python + Textual runtime → Application shell: provides runtime
- Application shell → Commands & messages: coordinates
- Application shell → Request editor: hosts
- Application shell → Response views: hosts
- Application shell → Collections: browses requests
- Commands & messages → Request editor: drives actions
- Request editor → Auth editor: composes auth
- Request editor → Variables & environments: resolves fields
- Variable autocomplete → Variables & environments: suggests values
- Request editor → Authentication builder: supplies auth settings
- Application shell → Authentication builder: executes request with
- Application shell → User scripts: runs around request
- Application shell → User-selected HTTP service: sends HTTP request
- User-selected HTTP service → Response views: returns response
- Response views → Syntax highlighting: highlights content
- Collections → Collection files: uses
- Collection files → YAML documents: reads and writes
- Save flow → Collections: persists editor output
- Request editor → Save flow: saves request
- Variables & environments → YAML documents: loads environments
- cURL import/export → Collections: imports / exports requests
- Postman import → Collections: imports collections
- OpenAPI import → Collections: imports specifications