# pranavsandeep/sprawl architecture

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

- Interactive diagram: https://gitdiagram.com/pranavsandeep/sprawl
- Repository: https://github.com/pranavsandeep/sprawl

## Overview

Sprawl is a Windows command-line file-name search tool. The user initializes an index for a folder, searches by name, chooses a match, and Sprawl opens its location in Explorer. Initialization walks files and builds trigram postings plus path and document-ID mappings; a companion process then consumes NTFS journal changes to keep those structures current. The README is empty, so the documented product surface is inferred from the command handling in `sprawl/src/main.rs`. Some updater and CLI implementation is unsampled; links below reflect only visible calls and the described behavior in sampled code.

Main entry points: [`sprawl-search/src/update_helper.rs`](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-search/src/update_helper.rs) (Change handlers), [`sprawl/src/main.rs`](https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs) (Initialize index), [`sprawl-core/src/index.rs`](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/index.rs) (Trigram index access), [`sprawl-core/src/path_list.rs`](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/path_list.rs) (Path mappings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Interactive CLI"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_init["Initialize index<br/>[main.rs]"]
  node_search["Search and select<br/>[main.rs]"]
end

subgraph group_index["Index and search"]
  node_walker["Filesystem walk<br/>[dir_walk.rs]"]
  node_trigrams["Trigram generation<br/>[util.rs]"]
  node_indexapi["Trigram index access<br/>[index.rs]"]
end

subgraph group_state["Index state"]
  node_pathlist["Path mappings<br/>[path_list.rs]"]
  node_docstore["Document mappings<br/>[doc_store.rs]"]
  node_postings[("Trigram postings")]
  node_pathsdb[("Path databases")]
  node_docsdb[("Document databases")]
end

subgraph group_live["Live updates"]
  node_updater["Journal updater<br/>[main.rs]"]
  node_updateops["Change handlers<br/>[update_helper.rs]"]
  node_win["Windows journal access<br/>[win_helper.rs]"]
  node_controlpipe["Control pipe"]
end

node_person(("User"))
node_explorer["Windows Explorer"]
node_ntfs[("NTFS journal")]
node_walkfs["Indexed filesystem"]

node_person -->|"enters commands"| node_cli
node_cli -->|"dispatches init"| node_init
node_cli -->|"dispatches search"| node_search
node_init -->|"walks folders"| node_walker
node_init -->|"builds mappings"| node_pathlist
node_init -->|"generates keys"| node_trigrams
node_init -->|"builds index"| node_indexapi
node_init -->|"creates mappings"| node_docstore
node_walker -->|"reads files"| node_walkfs
node_pathlist -->|"reads and writes"| node_pathsdb
node_indexapi -->|"reads and writes"| node_postings
node_docstore -->|"reads and writes"| node_docsdb
node_search -->|"generates query keys"| node_trigrams
node_search -->|"looks up matches"| node_indexapi
node_search -->|"resolves matches"| node_docstore
node_search -->|"resolves paths"| node_pathlist
node_search -->|"opens selection"| node_explorer
node_updater -->|"queries journal"| node_win
node_win -->|"reads changes"| node_ntfs
node_updater -->|"handles events"| node_updateops
node_updateops -->|"generates keys"| node_trigrams
node_updateops -->|"updates postings"| node_indexapi
node_updateops -->|"updates paths"| node_pathlist
node_updateops -->|"updates mappings"| node_docstore
node_updateops -->|"writes postings"| node_postings
node_updateops -->|"writes paths"| node_pathsdb
node_updateops -->|"writes mappings"| node_docsdb
node_cli -->|"signals pause"| node_controlpipe
node_updater -->|"listens for control"| node_controlpipe

click node_cli "https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs"
click node_init "https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs"
click node_search "https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs"
click node_walker "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/dir_walk.rs"
click node_trigrams "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/util.rs"
click node_indexapi "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/index.rs"
click node_pathlist "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/path_list.rs"
click node_docstore "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/doc_store.rs"
click node_updater "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-search/src/main.rs"
click node_updateops "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-search/src/update_helper.rs"
click node_win "https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/win_helper.rs"

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_init,node_search,node_person toneBlue
class node_walker,node_trigrams,node_indexapi,node_ntfs toneAmber
class node_pathlist,node_docstore,node_postings,node_pathsdb,node_docsdb toneMint
class node_updater,node_updateops,node_win,node_controlpipe toneRose
class node_explorer,node_walkfs toneIndigo
```

## Components

### Interactive CLI

- [CLI commands](https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs): `sprawl/src/main.rs`
- [Initialize index](https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs): `sprawl/src/main.rs`
- [Search and select](https://github.com/pranavsandeep/sprawl/blob/master/sprawl/src/main.rs): `sprawl/src/main.rs`

### Index and search

- [Filesystem walk](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/dir_walk.rs): `sprawl-core/src/dir_walk.rs`
- [Trigram generation](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/util.rs): `sprawl-core/src/util.rs`
- [Trigram index access](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/index.rs): `sprawl-core/src/index.rs`

### Index state

- [Path mappings](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/path_list.rs): `sprawl-core/src/path_list.rs`
- [Document mappings](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/doc_store.rs): `sprawl-core/src/doc_store.rs`
- **Trigram postings**
- **Path databases**
- **Document databases**

### Live updates

- [Journal updater](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-search/src/main.rs): `sprawl-search/src/main.rs`
- [Change handlers](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-search/src/update_helper.rs): `sprawl-search/src/update_helper.rs`
- [Windows journal access](https://github.com/pranavsandeep/sprawl/blob/master/sprawl-core/src/win_helper.rs): `sprawl-core/src/win_helper.rs`
- **Control pipe**

### Other components

- **User**
- **Windows Explorer**
- **NTFS journal**
- **Indexed filesystem**

## Connections

- User → CLI commands: enters commands
- CLI commands → Initialize index: dispatches init
- CLI commands → Search and select: dispatches search
- Initialize index → Filesystem walk: walks folders
- Initialize index → Path mappings: builds mappings
- Initialize index → Trigram generation: generates keys
- Initialize index → Trigram index access: builds index
- Initialize index → Document mappings: creates mappings
- Filesystem walk → Indexed filesystem: reads files
- Path mappings → Path databases: reads and writes
- Trigram index access → Trigram postings: reads and writes
- Document mappings → Document databases: reads and writes
- Search and select → Trigram generation: generates query keys
- Search and select → Trigram index access: looks up matches
- Search and select → Document mappings: resolves matches
- Search and select → Path mappings: resolves paths
- Search and select → Windows Explorer: opens selection
- Journal updater → Windows journal access: queries journal
- Windows journal access → NTFS journal: reads changes
- Journal updater → Change handlers: handles events
- Change handlers → Trigram generation: generates keys
- Change handlers → Trigram index access: updates postings
- Change handlers → Path mappings: updates paths
- Change handlers → Document mappings: updates mappings
- Change handlers → Trigram postings: writes postings
- Change handlers → Path databases: writes paths
- Change handlers → Document databases: writes mappings
- CLI commands → Control pipe: signals pause
- Journal updater → Control pipe: listens for control