# junegunn/fzf architecture

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

- Interactive diagram: https://gitdiagram.com/junegunn/fzf
- Repository: https://github.com/junegunn/fzf

## Overview

fzf is a command-line fuzzy finder and interactive terminal toolkit. The principal flow is option parsing, candidate ingestion, pattern matching, then interactive selection or filtered output. Matching is split between query parsing and optimized algorithms; terminal presentation supports renderer backends and ANSI-aware text. The supplied README excerpt establishes the product’s broader programmable-workflow context, but does not include detailed capability descriptions. Several runtime relationships are only partially visible in the sampled source, so those links are omitted or marked unverified.

Main entry points: [`src/core.go`](https://github.com/junegunn/fzf/blob/master/src/core.go) (Run orchestration), [`src/pattern.go`](https://github.com/junegunn/fzf/blob/master/src/pattern.go) (Pattern matching), [`src/tui/tui.go`](https://github.com/junegunn/fzf/blob/master/src/tui/tui.go) (TUI abstractions), [`main.go`](https://github.com/junegunn/fzf/blob/master/main.go) (Command entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and orchestration"]
  node_cli["Command entry<br/>[main.go]"]
  node_options["Option parsing<br/>[options.go]"]
  node_core["Run orchestration<br/>[core.go]"]
end

subgraph group_search["Search pipeline"]
  node_reader["Input reader<br/>[reader.go]"]
  node_item["Candidate items<br/>[item.go]"]
  node_tokenizer["Query tokenization<br/>[tokenizer.go]"]
  node_pattern["Pattern matching<br/>[pattern.go]"]
  node_algo["Fuzzy algorithms<br/>[algo.go]"]
  node_result["Match results<br/>[result.go]"]
  node_merger["Result ordering<br/>[merger.go]"]
end

subgraph group_terminal["Terminal interface"]
  node_ansi["ANSI processing<br/>[ansi.go]"]
  node_terminal_ui["Interactive terminal<br/>[terminal.go]"]
  node_tui_api["TUI abstractions<br/>[tui.go]"]
  node_light["Light renderer<br/>[light.go]"]
  node_tcell["Fullscreen renderer<br/>[tcell.go]"]
  node_tmux["Tmux display<br/>[tmux.go]"]
end

subgraph group_runtime["Runtime services"]
  node_server["Server mode<br/>[server.go]"]
  node_cache[("Match cache<br/>[cache.go]")]
end

node_user(("CLI user"))
node_candidates["Candidate input"]
node_stdout(("Output stream"))

node_user -->|"runs"| node_cli
node_cli -->|"parses arguments"| node_options
node_cli -->|"runs finder"| node_core
node_candidates -.->|"supplies items"| node_reader
node_core -.->|"reads candidates"| node_reader
node_core -->|"creates terminal"| node_terminal_ui
node_core -->|"matches items"| node_pattern
node_pattern -->|"dispatches match"| node_algo
node_core -.->|"prints results"| node_stdout
node_pattern -.->|"builds matches"| node_result
node_result -.->|"orders matches"| node_merger
node_ansi -->|"scans escape bytes"| node_algo
node_ansi -->|"uses color types"| node_tui_api
node_terminal_ui -.->|"uses interface"| node_tui_api
node_tui_api -.->|"selects backend"| node_light
node_tui_api -.->|"selects backend"| node_tcell
node_core -->|"dispatches display"| node_tmux
node_user -.->|"requests service"| node_server
node_pattern -.->|"caches matches"| node_cache

click node_cli "https://github.com/junegunn/fzf/blob/master/main.go"
click node_options "https://github.com/junegunn/fzf/blob/master/src/options.go"
click node_core "https://github.com/junegunn/fzf/blob/master/src/core.go"
click node_reader "https://github.com/junegunn/fzf/blob/master/src/reader.go"
click node_item "https://github.com/junegunn/fzf/blob/master/src/item.go"
click node_tokenizer "https://github.com/junegunn/fzf/blob/master/src/tokenizer.go"
click node_pattern "https://github.com/junegunn/fzf/blob/master/src/pattern.go"
click node_algo "https://github.com/junegunn/fzf/blob/master/src/algo/algo.go"
click node_result "https://github.com/junegunn/fzf/blob/master/src/result.go"
click node_merger "https://github.com/junegunn/fzf/blob/master/src/merger.go"
click node_ansi "https://github.com/junegunn/fzf/blob/master/src/ansi.go"
click node_terminal_ui "https://github.com/junegunn/fzf/blob/master/src/terminal.go"
click node_tui_api "https://github.com/junegunn/fzf/blob/master/src/tui/tui.go"
click node_light "https://github.com/junegunn/fzf/blob/master/src/tui/light.go"
click node_tcell "https://github.com/junegunn/fzf/blob/master/src/tui/tcell.go"
click node_tmux "https://github.com/junegunn/fzf/blob/master/src/tmux.go"
click node_server "https://github.com/junegunn/fzf/blob/master/src/server.go"
click node_cache "https://github.com/junegunn/fzf/blob/master/src/cache.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_cli,node_options,node_core,node_user toneBlue
class node_reader,node_item,node_tokenizer,node_pattern,node_algo,node_result,node_merger toneAmber
class node_ansi,node_terminal_ui,node_tui_api,node_light,node_tcell,node_tmux toneMint
class node_server,node_cache toneRose
class node_candidates,node_stdout toneIndigo
```

## Components

### CLI and orchestration

- [Command entry](https://github.com/junegunn/fzf/blob/master/main.go): `main.go`
- [Option parsing](https://github.com/junegunn/fzf/blob/master/src/options.go): `src/options.go`
- [Run orchestration](https://github.com/junegunn/fzf/blob/master/src/core.go): `src/core.go`

### Search pipeline

- [Input reader](https://github.com/junegunn/fzf/blob/master/src/reader.go): `src/reader.go`
- [Candidate items](https://github.com/junegunn/fzf/blob/master/src/item.go): `src/item.go`
- [Query tokenization](https://github.com/junegunn/fzf/blob/master/src/tokenizer.go): `src/tokenizer.go`
- [Pattern matching](https://github.com/junegunn/fzf/blob/master/src/pattern.go): `src/pattern.go`
- [Fuzzy algorithms](https://github.com/junegunn/fzf/blob/master/src/algo/algo.go): `src/algo/algo.go`
- [Match results](https://github.com/junegunn/fzf/blob/master/src/result.go): `src/result.go`
- [Result ordering](https://github.com/junegunn/fzf/blob/master/src/merger.go): `src/merger.go`

### Terminal interface

- [ANSI processing](https://github.com/junegunn/fzf/blob/master/src/ansi.go): `src/ansi.go`
- [Interactive terminal](https://github.com/junegunn/fzf/blob/master/src/terminal.go): `src/terminal.go`
- [TUI abstractions](https://github.com/junegunn/fzf/blob/master/src/tui/tui.go): `src/tui/tui.go`
- [Light renderer](https://github.com/junegunn/fzf/blob/master/src/tui/light.go): `src/tui/light.go`
- [Fullscreen renderer](https://github.com/junegunn/fzf/blob/master/src/tui/tcell.go): `src/tui/tcell.go`
- [Tmux display](https://github.com/junegunn/fzf/blob/master/src/tmux.go): `src/tmux.go`

### Runtime services

- [Server mode](https://github.com/junegunn/fzf/blob/master/src/server.go): `src/server.go`
- [Match cache](https://github.com/junegunn/fzf/blob/master/src/cache.go): `src/cache.go`

### Other components

- **CLI user**
- **Candidate input**
- **Output stream**

## Connections

- CLI user → Command entry: runs
- Command entry → Option parsing: parses arguments (evidence: `main.go`)
- Command entry → Run orchestration: runs finder (evidence: `main.go`)
- Candidate input → Input reader: supplies items
- Run orchestration → Input reader: reads candidates
- Run orchestration → Interactive terminal: creates terminal (evidence: `src/core.go`)
- Run orchestration → Pattern matching: matches items (evidence: `src/core.go`)
- Pattern matching → Fuzzy algorithms: dispatches match (evidence: `src/pattern.go`)
- Run orchestration → Output stream: prints results
- Pattern matching → Match results: builds matches
- Match results → Result ordering: orders matches
- ANSI processing → Fuzzy algorithms: scans escape bytes (evidence: `src/ansi.go`)
- ANSI processing → TUI abstractions: uses color types (evidence: `src/ansi.go`)
- Interactive terminal → TUI abstractions: uses interface
- TUI abstractions → Light renderer: selects backend
- TUI abstractions → Fullscreen renderer: selects backend
- Run orchestration → Tmux display: dispatches display (evidence: `src/core.go`)
- CLI user → Server mode: requests service
- Pattern matching → Match cache: caches matches
