# darrenburns/posting architecture

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

- Interactive diagram: https://gitdiagram.com/darrenburns/posting
- Repository: https://github.com/darrenburns/posting

## Overview

#### 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: [`src/posting/app.py`](https://github.com/darrenburns/posting/blob/main/src/posting/app.py) (Application shell), [`src/posting/widgets/request/request_editor.py`](https://github.com/darrenburns/posting/blob/main/src/posting/widgets/request/request_editor.py) (Request editor), [`src/posting/collection.py`](https://github.com/darrenburns/posting/blob/main/src/posting/collection.py) (Collections), [`src/posting/widgets/response/response_area.py`](https://github.com/darrenburns/posting/blob/main/src/posting/widgets/response/response_area.py) (Response views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tui["Terminal UI"]
  node_app["Application shell<br/>Textual app<br/>[app.py]"]
  node_commands["Commands &amp; messages<br/>UI coordination<br/>[commands.py]"]
  node_editor["Request editor<br/>authoring UI<br/>[request_editor.py]"]
  node_request_auth["Auth editor<br/>request UI<br/>[request_auth.py]"]
  node_response["Response views<br/>rendering UI<br/>[response_area.py]"]
  node_highlighting["Syntax highlighting<br/>Tree-sitter integration<br/>[highlighters.py]"]
  node_autocomplete["Variable autocomplete<br/>input UI"]
end

subgraph group_data["Local request data"]
  node_collections["Collections<br/>collection service<br/>[collection.py]"]
  node_files["Collection files<br/>file service<br/>[files.py]"]
  node_save_request["Save flow<br/>persistence UI<br/>[save_request.py]"]
  node_yaml_store[("YAML documents<br/>local filesystem<br/>[yaml.py]")]
  node_variables["Variables &amp; environments<br/>resolution service<br/>[variables.py]"]
  node_scripts{{"User scripts<br/>extension runtime<br/>[scripts.py]"}}
end

subgraph group_interop["Interoperability"]
  node_curl_import["cURL import/export<br/>adapter<br/>[curl.py]"]
  node_postman_import["Postman import<br/>adapter<br/>[postman.py]"]
  node_openapi_import["OpenAPI import<br/>adapter<br/>[open_api.py]"]
end

node_cli["CLI entry point<br/>Python CLI<br/>[__main__.py]"]
node_auth["Authentication builder<br/>execution support<br/>[auth.py]"]
node_http_target{{"User-selected HTTP service<br/>external HTTP API"}}
node_runtime["Python + Textual runtime<br/>project runtime<br/>[pyproject.toml]"]

node_cli -->|"starts"| node_app
node_runtime -.->|"provides runtime"| node_app
node_app -->|"coordinates"| node_commands
node_app -->|"hosts"| node_editor
node_app -->|"hosts"| node_response
node_app -->|"browses requests"| node_collections
node_commands -->|"drives actions"| node_editor
node_editor -->|"composes auth"| node_request_auth
node_editor -->|"resolves fields"| node_variables
node_autocomplete -->|"suggests values"| node_variables
node_editor -->|"supplies auth settings"| node_auth
node_app -->|"executes request with"| node_auth
node_app -->|"runs around request"| node_scripts
node_app -->|"sends HTTP request"| node_http_target
node_http_target -->|"returns response"| node_response
node_response -->|"highlights content"| node_highlighting
node_collections -->|"uses"| node_files
node_files -->|"reads and writes"| node_yaml_store
node_save_request -->|"persists editor output"| node_collections
node_editor -->|"saves request"| node_save_request
node_variables -->|"loads environments"| node_yaml_store
node_curl_import -->|"imports / exports requests"| node_collections
node_postman_import -->|"imports collections"| node_collections
node_openapi_import -->|"imports specifications"| node_collections

click node_cli "https://github.com/darrenburns/posting/blob/main/src/posting/__main__.py"
click node_app "https://github.com/darrenburns/posting/blob/main/src/posting/app.py"
click node_commands "https://github.com/darrenburns/posting/blob/main/src/posting/commands.py"
click node_editor "https://github.com/darrenburns/posting/blob/main/src/posting/widgets/request/request_editor.py"
click node_request_auth "https://github.com/darrenburns/posting/blob/main/src/posting/widgets/request/request_auth.py"
click node_response "https://github.com/darrenburns/posting/blob/main/src/posting/widgets/response/response_area.py"
click node_highlighting "https://github.com/darrenburns/posting/blob/main/src/posting/highlighters.py"
click node_collections "https://github.com/darrenburns/posting/blob/main/src/posting/collection.py"
click node_files "https://github.com/darrenburns/posting/blob/main/src/posting/files.py"
click node_save_request "https://github.com/darrenburns/posting/blob/main/src/posting/save_request.py"
click node_yaml_store "https://github.com/darrenburns/posting/blob/main/src/posting/yaml.py"
click node_variables "https://github.com/darrenburns/posting/blob/main/src/posting/variables.py"
click node_autocomplete "https://github.com/darrenburns/posting/blob/main/src/posting/widgets/variable_autocomplete.py"
click node_scripts "https://github.com/darrenburns/posting/blob/main/src/posting/scripts.py"
click node_auth "https://github.com/darrenburns/posting/blob/main/src/posting/auth.py"
click node_curl_import "https://github.com/darrenburns/posting/blob/main/src/posting/importing/curl.py"
click node_postman_import "https://github.com/darrenburns/posting/blob/main/src/posting/importing/postman.py"
click node_openapi_import "https://github.com/darrenburns/posting/blob/main/src/posting/importing/open_api.py"
click node_runtime "https://github.com/darrenburns/posting/blob/main/pyproject.toml"

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_commands,node_editor,node_request_auth,node_response,node_highlighting,node_autocomplete toneBlue
class node_collections,node_files,node_save_request,node_yaml_store,node_variables,node_scripts toneAmber
class node_curl_import,node_postman_import,node_openapi_import toneMint
class node_cli,node_auth,node_http_target,node_runtime toneNeutral
```

## Components

### Terminal UI

Textual application and interactive views.

- [Application shell](https://github.com/darrenburns/posting/blob/main/src/posting/app.py): Textual app · Owns lifecycle, screens, commands, and cross-widget messaging. · `src/posting/app.py`
- [Commands & messages](https://github.com/darrenburns/posting/blob/main/src/posting/commands.py): UI coordination · `src/posting/commands.py`
- [Request editor](https://github.com/darrenburns/posting/blob/main/src/posting/widgets/request/request_editor.py): authoring UI · Builds the editable HTTP request model. · `src/posting/widgets/request/request_editor.py`
- [Auth editor](https://github.com/darrenburns/posting/blob/main/src/posting/widgets/request/request_auth.py): request UI · `src/posting/widgets/request/request_auth.py`
- [Response views](https://github.com/darrenburns/posting/blob/main/src/posting/widgets/response/response_area.py): rendering UI · Renders status, headers, cookies, body, traces, and script output. · `src/posting/widgets/response/response_area.py`
- [Syntax highlighting](https://github.com/darrenburns/posting/blob/main/src/posting/highlighters.py): Tree-sitter integration · `src/posting/highlighters.py`
- [Variable autocomplete](https://github.com/darrenburns/posting/blob/main/src/posting/widgets/variable_autocomplete.py): input UI · `src/posting/widgets/variable_autocomplete.py`

### Local request data

YAML-backed collections, environments, and scripts.

- [Collections](https://github.com/darrenburns/posting/blob/main/src/posting/collection.py): collection service · Loads, enumerates, saves, and locates request definitions. · `src/posting/collection.py`
- [Collection files](https://github.com/darrenburns/posting/blob/main/src/posting/files.py): file service · `src/posting/files.py`
- [Save flow](https://github.com/darrenburns/posting/blob/main/src/posting/save_request.py): persistence UI · `src/posting/save_request.py`
- [YAML documents](https://github.com/darrenburns/posting/blob/main/src/posting/yaml.py): local filesystem · Durable request collections and environment files. · `src/posting/yaml.py`
- [Variables & environments](https://github.com/darrenburns/posting/blob/main/src/posting/variables.py): resolution service · Resolves reusable environment values for request fields. · `src/posting/variables.py`
- [User scripts](https://github.com/darrenburns/posting/blob/main/src/posting/scripts.py): extension runtime · Runs user Python around request execution. · `src/posting/scripts.py`

### Interoperability

Request format translation at the application boundary.

- [cURL import/export](https://github.com/darrenburns/posting/blob/main/src/posting/importing/curl.py): adapter · `src/posting/importing/curl.py`
- [Postman import](https://github.com/darrenburns/posting/blob/main/src/posting/importing/postman.py): adapter · `src/posting/importing/postman.py`
- [OpenAPI import](https://github.com/darrenburns/posting/blob/main/src/posting/importing/open_api.py): adapter · `src/posting/importing/open_api.py`

### Other components

- [CLI entry point](https://github.com/darrenburns/posting/blob/main/src/posting/__main__.py): Python CLI · `src/posting/__main__.py`
- [Authentication builder](https://github.com/darrenburns/posting/blob/main/src/posting/auth.py): execution support · `src/posting/auth.py`
- **User-selected HTTP service**: external HTTP API · Arbitrary remote endpoint selected by the user.
- [Python + Textual runtime](https://github.com/darrenburns/posting/blob/main/pyproject.toml): project runtime · `pyproject.toml`

## Connections

- 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
