# seruman/px architecture

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

- Interactive diagram: https://gitdiagram.com/seruman/px
- Repository: https://github.com/seruman/px

## Overview

px is a terminal picker that reads piped text, finds selectable spans, displays the original formatted lines interactively, and prints confirmed selections to stdout. Its main workflow is input scanning and optional wrapped-line rejoining, matcher resolution and span discovery, interactive navigation/selection, then output. Built-in matchers and executable extensions are distinct discovery paths. Source excerpts are incomplete, so the graph omits uncertain UI-internal wiring and focuses on documented capabilities and supported calls.

Main entry points: [`main.go`](https://github.com/seruman/px/blob/main/main.go) (CLI entry), [`extension.go`](https://github.com/seruman/px/blob/main/extension.go) (Matcher execution), [`picker.go`](https://github.com/seruman/px/blob/main/picker.go) (Picker interface), [`match.go`](https://github.com/seruman/px/blob/main/match.go) (Built-in matchers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input handling"]
  node_main["CLI entry<br/>[main.go]"]
  node_lineio["Line scanning<br/>[paths.go]"]
  node_unwrap["Wrapped-line joining<br/>[paths.go]"]
end

subgraph group_matching["Match discovery"]
  node_matcherresolve["Matcher resolution<br/>[main.go]"]
  node_builtins["Built-in matchers<br/>[match.go]"]
  node_pathmatcher["Path matcher<br/>[paths.go]"]
  node_regexmatcher["Custom regex<br/>[match.go]"]
  node_matchrun["Matcher execution<br/>[extension.go]"]
  node_extension["px extension"]
  node_spanparse["Span validation<br/>[extension.go]"]
  node_styleinput["Styled input<br/>[extension.go]"]
end

subgraph group_picker["Interactive picker"]
  node_picker["Picker interface<br/>[picker.go]"]
  node_navigation["Navigate and select<br/>[picker.go]"]
  node_search["Search and hints<br/>[picker.go]"]
end

subgraph group_output["Output"]
  node_stdout(("Selection consumer"))
end

node_producer(("Piped command"))
node_terminal(("Terminal user"))

node_producer -->|"pipes text"| node_main
node_main -->|"scans input"| node_lineio
node_main -->|"rejoins lines"| node_unwrap
node_main -->|"resolves options"| node_matcherresolve
node_matcherresolve -->|"selects built-ins"| node_builtins
node_matcherresolve -.->|"locates executable"| node_extension
node_main -->|"compiles regex"| node_regexmatcher
node_main -->|"starts matchers"| node_matchrun
node_matchrun -->|"runs functions"| node_builtins
node_builtins -->|"matches paths"| node_pathmatcher
node_matchrun -.->|"sends lines"| node_extension
node_extension -.->|"returns spans"| node_matchrun
node_matchrun -->|"validates spans"| node_spanparse
node_matchrun -->|"styles lines"| node_styleinput
node_main -->|"runs interface"| node_picker
node_matchrun -->|"posts match data"| node_picker
node_terminal -->|"sends keys"| node_picker
node_picker -->|"handles navigation"| node_navigation
node_picker -->|"handles search"| node_search
node_picker -->|"returns selection"| node_main
node_main -->|"prints selection"| node_stdout

click node_main "https://github.com/seruman/px/blob/main/main.go"
click node_lineio "https://github.com/seruman/px/blob/main/paths.go"
click node_unwrap "https://github.com/seruman/px/blob/main/paths.go"
click node_matcherresolve "https://github.com/seruman/px/blob/main/main.go"
click node_builtins "https://github.com/seruman/px/blob/main/match.go"
click node_pathmatcher "https://github.com/seruman/px/blob/main/paths.go"
click node_regexmatcher "https://github.com/seruman/px/blob/main/match.go"
click node_matchrun "https://github.com/seruman/px/blob/main/extension.go"
click node_spanparse "https://github.com/seruman/px/blob/main/extension.go"
click node_styleinput "https://github.com/seruman/px/blob/main/extension.go"
click node_picker "https://github.com/seruman/px/blob/main/picker.go"
click node_navigation "https://github.com/seruman/px/blob/main/picker.go"
click node_search "https://github.com/seruman/px/blob/main/picker.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_main,node_lineio,node_unwrap,node_terminal toneBlue
class node_matcherresolve,node_builtins,node_pathmatcher,node_regexmatcher,node_matchrun,node_extension,node_spanparse,node_styleinput toneAmber
class node_picker,node_navigation,node_search toneMint
class node_stdout toneRose
class node_producer toneIndigo
```

## Components

### Input handling

- [CLI entry](https://github.com/seruman/px/blob/main/main.go): `main.go`
- [Line scanning](https://github.com/seruman/px/blob/main/paths.go): `paths.go`
- [Wrapped-line joining](https://github.com/seruman/px/blob/main/paths.go): `paths.go`

### Match discovery

- [Matcher resolution](https://github.com/seruman/px/blob/main/main.go): `main.go`
- [Built-in matchers](https://github.com/seruman/px/blob/main/match.go): `match.go`
- [Path matcher](https://github.com/seruman/px/blob/main/paths.go): `paths.go`
- [Custom regex](https://github.com/seruman/px/blob/main/match.go): `match.go`
- [Matcher execution](https://github.com/seruman/px/blob/main/extension.go): `extension.go`
- **px extension**
- [Span validation](https://github.com/seruman/px/blob/main/extension.go): `extension.go`
- [Styled input](https://github.com/seruman/px/blob/main/extension.go): `extension.go`

### Interactive picker

- [Picker interface](https://github.com/seruman/px/blob/main/picker.go): `picker.go`
- [Navigate and select](https://github.com/seruman/px/blob/main/picker.go): `picker.go`
- [Search and hints](https://github.com/seruman/px/blob/main/picker.go): `picker.go`

### Output

- **Selection consumer**

### Other components

- **Piped command**
- **Terminal user**

## Connections

- Piped command → CLI entry: pipes text
- CLI entry → Line scanning: scans input
- CLI entry → Wrapped-line joining: rejoins lines
- CLI entry → Matcher resolution: resolves options
- Matcher resolution → Built-in matchers: selects built-ins
- Matcher resolution → px extension: locates executable
- CLI entry → Custom regex: compiles regex
- CLI entry → Matcher execution: starts matchers
- Matcher execution → Built-in matchers: runs functions
- Built-in matchers → Path matcher: matches paths
- Matcher execution → px extension: sends lines
- px extension → Matcher execution: returns spans
- Matcher execution → Span validation: validates spans
- Matcher execution → Styled input: styles lines
- CLI entry → Picker interface: runs interface
- Matcher execution → Picker interface: posts match data
- Terminal user → Picker interface: sends keys
- Picker interface → Navigate and select: handles navigation
- Picker interface → Search and hints: handles search
- Picker interface → CLI entry: returns selection
- CLI entry → Selection consumer: prints selection