# romantrnt/zipsearch architecture

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

- Interactive diagram: https://gitdiagram.com/romantrnt/zipsearch
- Repository: https://github.com/romantrnt/zipsearch

## Overview

ZipSearch is an offline terminal application for searching ZIP collections in place. Users start through the CLI or keyboard-driven TUI, choose literal, regex, SMART, or advanced-query behavior, and receive archive/member/record matches for inspection or export. Searches scan source archives directly or use an optional candidate index; indexed candidates are reopened and verified against original archive data. The graph covers the documented data formats and inspection features, but some subsystem links are documented rather than visible in the sampled implementation excerpts.

Main entry points: [`src/zipsearch/tui.py`](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/tui.py) (Interactive TUI), [`src/zipsearch/cli.py`](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/cli.py) (CLI commands), [`src/zipsearch/engine.py`](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/engine.py) (Archive search engine), [`src/zipsearch/grouping.py`](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/grouping.py) (Result grouping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_tui["Interactive TUI<br/>[tui.py]"]
  node_state["UI state<br/>[state.py]"]
end

subgraph group_search["Search and extraction"]
  node_engine["Archive search engine<br/>[engine.py]"]
  node_query["Advanced query parser<br/>[query.py]"]
  node_smart["SMART matching<br/>[smart.py]"]
  node_archive[("ZIP collection")]
  node_formats["Structured member readers<br/>[engine.py]"]
end

subgraph group_indexing["Index and planning"]
  node_execution["Search planner<br/>[execution.py]"]
  node_index[("Candidate index<br/>[index.py]")]
end

subgraph group_results["Results and inspection"]
  node_models["Search data models<br/>[models.py]"]
  node_entities["Entity extraction<br/>[entities.py]"]
  node_grouping["Result grouping<br/>[grouping.py]"]
  node_render["CLI rendering<br/>[render.py]"]
  node_inspect["Archive inspection<br/>[cli.py]"]
end

node_user(("Terminal user"))

node_user -->|"runs commands"| node_cli
node_user -->|"inspects interactively"| node_tui
node_cli -->|"plans search"| node_execution
node_cli -->|"opens TUI"| node_tui
node_cli -->|"manages index"| node_index
node_cli -->|"renders matches"| node_render
node_cli -->|"groups results"| node_grouping
node_cli -->|"inspects directory"| node_inspect
node_tui -.->|"persists preferences"| node_state
node_execution -->|"looks up candidates"| node_index
node_execution -->|"scans archives"| node_engine
node_index -->|"indexes metadata"| node_archive
node_engine -->|"reads members"| node_archive
node_engine -->|"matches SMART"| node_smart
node_engine -.->|"evaluates advanced queries"| node_query
node_engine -->|"reads structured data"| node_formats
node_engine -->|"produces matches"| node_models
node_grouping -->|"extracts entities"| node_entities
node_grouping -->|"normalizes phones"| node_smart
node_render -->|"formats matches"| node_models
node_tui -->|"searches archives"| node_engine
node_tui -.->|"groups occurrences"| node_grouping
node_tui -->|"navigates entities"| node_entities
node_tui -.->|"shows index status"| node_index
node_tui -.->|"inspects results"| node_models

click node_cli "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/cli.py"
click node_tui "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/tui.py"
click node_state "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/state.py"
click node_execution "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/execution.py"
click node_index "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/index.py"
click node_engine "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/engine.py"
click node_query "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/query.py"
click node_smart "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/smart.py"
click node_models "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/models.py"
click node_entities "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/entities.py"
click node_grouping "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/grouping.py"
click node_render "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/render.py"
click node_inspect "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/cli.py"
click node_formats "https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/engine.py"

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_tui,node_state,node_user toneBlue
class node_engine,node_query,node_smart,node_archive,node_formats toneAmber
class node_execution,node_index toneMint
class node_models,node_entities,node_grouping,node_render,node_inspect toneRose
```

## Components

### User interfaces

- [CLI commands](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/cli.py): `src/zipsearch/cli.py`
- [Interactive TUI](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/tui.py): `src/zipsearch/tui.py`
- [UI state](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/state.py): `src/zipsearch/state.py`

### Search and extraction

- [Archive search engine](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/engine.py): `src/zipsearch/engine.py`
- [Advanced query parser](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/query.py): `src/zipsearch/query.py`
- [SMART matching](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/smart.py): `src/zipsearch/smart.py`
- **ZIP collection**
- [Structured member readers](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/engine.py): `src/zipsearch/engine.py`

### Index and planning

- [Search planner](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/execution.py): `src/zipsearch/execution.py`
- [Candidate index](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/index.py): `src/zipsearch/index.py`

### Results and inspection

- [Search data models](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/models.py): `src/zipsearch/models.py`
- [Entity extraction](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/entities.py): `src/zipsearch/entities.py`
- [Result grouping](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/grouping.py): `src/zipsearch/grouping.py`
- [CLI rendering](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/render.py): `src/zipsearch/render.py`
- [Archive inspection](https://github.com/romantrnt/zipsearch/blob/main/src/zipsearch/cli.py): `src/zipsearch/cli.py`

### Other components

- **Terminal user**

## Connections

- Terminal user → CLI commands: runs commands (evidence: `README.md`)
- Terminal user → Interactive TUI: inspects interactively (evidence: `README.md`)
- CLI commands → Search planner: plans search (evidence: `src/zipsearch/cli.py`)
- CLI commands → Interactive TUI: opens TUI (evidence: `src/zipsearch/cli.py`)
- CLI commands → Candidate index: manages index (evidence: `src/zipsearch/cli.py`)
- CLI commands → CLI rendering: renders matches (evidence: `src/zipsearch/cli.py`)
- CLI commands → Result grouping: groups results (evidence: `src/zipsearch/cli.py`)
- CLI commands → Archive inspection: inspects directory (evidence: `README.md`)
- Interactive TUI → UI state: persists preferences (evidence: `src/zipsearch/tui.py`)
- Search planner → Candidate index: looks up candidates (evidence: `src/zipsearch/execution.py`)
- Search planner → Archive search engine: scans archives (evidence: `src/zipsearch/execution.py`)
- Candidate index → ZIP collection: indexes metadata (evidence: `README.md`)
- Archive search engine → ZIP collection: reads members (evidence: `README.md`)
- Archive search engine → SMART matching: matches SMART (evidence: `src/zipsearch/engine.py`)
- Archive search engine → Advanced query parser: evaluates advanced queries (evidence: `src/zipsearch/engine.py`)
- Archive search engine → Structured member readers: reads structured data (evidence: `README.md`)
- Archive search engine → Search data models: produces matches (evidence: `src/zipsearch/engine.py`)
- Result grouping → Entity extraction: extracts entities (evidence: `src/zipsearch/grouping.py`)
- Result grouping → SMART matching: normalizes phones (evidence: `src/zipsearch/grouping.py`)
- CLI rendering → Search data models: formats matches (evidence: `src/zipsearch/render.py`)
- Interactive TUI → Archive search engine: searches archives (evidence: `README.md`)
- Interactive TUI → Result grouping: groups occurrences (evidence: `src/zipsearch/tui.py`)
- Interactive TUI → Entity extraction: navigates entities (evidence: `README.md`)
- Interactive TUI → Candidate index: shows index status (evidence: `src/zipsearch/tui.py`)
- Interactive TUI → Search data models: inspects results (evidence: `src/zipsearch/tui.py`)
