# denisidoro/navi architecture

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

- Interactive diagram: https://gitdiagram.com/denisidoro/navi
- Repository: https://github.com/denisidoro/navi

## Overview

##### Project type and purpose
- From the file tree and README, **navi** is a Rust-based, open-source, interactive command-line cheatsheet tool. It ships as a single CLI binary, integrates with various shells (bash, zsh, fish, PowerShell, Nu, Elvish), leverages external fuzzy-finder tools (fzf or skim), and can fetch or manage cheatsheet repositories (local or remote).

##### Key top-level directories and patterns
- **src/bin/main.rs**: entry point for the CLI executable.
- **src/commands/**: implements subcommands (core actor logic, functional commands, preview, repo, info, shell, temp).
- **src/clients/**: HTTP clients for external cheat services (cheat.sh, tldr).
- **src/config/**: CLI flags, environment variables, YAML config parsing.
- **src/common/**: shared utilities (filesystem, shell spawning, clipboard, URL, terminal, hashing).
- **src/finder/**: logic to locate and filter cheats from file system or remote sources.
- **src/parser.rs** & **src/deser/**: parsing the `.cheat` file syntax, deserializing into internal representations.
- **shell/**: shell widget scripts for various shells—how navi hooks into user’s shell.
- **scripts/**: automated tasks (install, test, release, docker).
- **docs/** & **tests/**: user documentation and automated test cases.

##### Main components
a. **User Interface Layer**
- Shell widget scripts (bash, zsh, fish, PS1, nu, elv)
- Direct invocation of the `navi` binary in a terminal
b. **navi Core (Rust Binary)**
- **CLI Parser & Dispatcher** (`src/bin/main.rs` + `structopt`/`clap`)
- **Command Modules** (`src/commands/*`): core actor, functional transforms, preview renderers, repository management, info, shell execution
- **Configuration Manager** (`src/config/*`): loads CLI flags, env vars, YAML config
- **Cheatsheet Finder** (`src/finder`): scans local `~/.local/share/navi/cheats/`, auto-updates remote repos via Git or HTTP
- **Parser & Deserializer** (`src/parser.rs`, `src/deser`): reads `.cheat` files into `structures`
- **Data Structures** (`src/structures/*`): in-memory representations of cheats, actions, suggestions
- **Common Utilities** (`src/common/*`): shell spawning, clipboard, terminal I/O, fs access
- **External Clients** (`src/clients/*`): fetch cheats from cheat.sh or tldr API
- **Integration with fuzzy-finder**: spawns `fzf` or `skim` as subprocess to let user filter suggestions
c. **External Dependencies**
- File system (local cheats directory, config files)
- Git (for repo import & updates)
- HTTP services (cheat.sh, tldr)
- fzf/skim (filters)
- Shell environment (executes chosen commands)

##### Relationships and data flow
- User presses widget keybind or runs `navi` → Shell widget or CLI passes control to the navi binary
- Binary bootstraps: loads configuration → scans local cheats (and optionally remote via Git/HTTP) → parses `.cheat` files → builds internal structures
- User navigates suggestions via fzf/skim subprocess → selection triggers preview or execution
- If user requests remote cheats, `src/clients/*` fetches data over HTTP and hands off to the parser
- Final command is output back to the shell for execution
- Repo commands (`navi repo add`, `navi repo browse`) invoke Git or HTTP and write to the local cheats directory

##### Architectural patterns and design principles
- **Layered architecture**: UI layer → CLI dispatch → business logic modules → data access (FS, HTTP, Git) → external tools
- **Modular command handlers**: each subcommand is a separate module (easily extensible)
- **Separation of concerns**: parsing/deserialization, CLI config, core logic, client I/O, common utilities
- **Plugin-like shell integration**: shell-specific scripts delegate to the same binary

##### Technologies, frameworks, libraries
- Rust and Cargo
- structopt / clap (CLI parsing)
- serde / serde_yaml (deserialization of `.cheat` files & config)
- Git2 or calling out to the `git` CLI (repo management)
- reqwest or similar HTTP client (cheat.sh, tldr)
- fzf / skim subprocess integration
- Shell scripting for integration (`shell/` directory)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Shell Widget Scripts"
        direction TB
        Bash["Bash Script"]:::ui
        Zsh["Zsh Script"]:::ui
        Fish["Fish Script"]:::ui
        PS1["PowerShell Script"]:::ui
        Nu["Nu Script"]:::ui
        Elv["Elvish Script"]:::ui
    end
    CLIInvocation["Direct CLI Invocation"]:::ui

    %% navi CLI Binary
    subgraph "navi CLI Binary"
        direction TB
        CLIParser["CLI Parser & Dispatcher"]:::core
        CommandModules["Command Modules"]:::core
        ConfigManager["Configuration Manager"]:::core
        Finder["Cheatsheet Finder"]:::core
        ParserDeserializer["Parser & Deserializer"]:::core
        DataStructures["Data Structures"]:::core
        CommonUtilities["Common Utilities"]:::core
        ExternalClients["External Clients"]:::core
        FuzzyIntegration["Fuzzy-Finder Integration"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        FileSystem["File System"]:::external
        Git["Git (CLI/Library)"]:::external
        HTTPAPIs["HTTP Services (cheat.sh, tldr)"]:::external
        FuzzyTool["fzf/skim"]:::external
        ShellEnv["Shell Environment"]:::external
        Scripts["Automated Tasks & CI Scripts"]:::external
        Docs["Documentation"]:::external
        Tests["Automated Tests"]:::external
    end

    %% Connections
    Bash -->|widget keybind| CLIParser
    Zsh -->|widget keybind| CLIParser
    Fish -->|widget keybind| CLIParser
    PS1 -->|widget keybind| CLIParser
    Nu -->|widget keybind| CLIParser
    Elv -->|widget keybind| CLIParser
    CLIInvocation -->|invokes| CLIParser

    CLIParser -->|"load config"| ConfigManager
    CLIParser -->|"dispatch command"| CommandModules

    CommandModules -->|"use finder"| Finder
    CommandModules -->|"use parser"| ParserDeserializer
    CommandModules -->|"use common utils"| CommonUtilities
    CommandModules -->|"use data structs"| DataStructures
    CommandModules -->|"invoke clients"| ExternalClients
    CommandModules -->|"spawn fuzzy"| FuzzyIntegration
    CommandModules -->|"output command"| ShellEnv

    Finder -->|"scan cheats"| FileSystem
    Finder -->|"git update"| Git

    ExternalClients -->|"fetch cheats"| HTTPAPIs

    ParserDeserializer -->|"parse .cheat"| DataStructures

    CommonUtilities -->|"spawn fzf/skim"| FuzzyTool

    FuzzyIntegration -->|"spawn fzf/skim"| FuzzyTool
    FuzzyIntegration -->|"selection feedback"| CommandModules

    %% Click Events
    click Bash "https://github.com/denisidoro/navi/blob/master/shell/navi.plugin.bash"
    click Zsh "https://github.com/denisidoro/navi/blob/master/shell/navi.plugin.zsh"
    click Fish "https://github.com/denisidoro/navi/blob/master/shell/navi.plugin.fish"
    click PS1 "https://github.com/denisidoro/navi/blob/master/shell/navi.plugin.ps1"
    click Nu "https://github.com/denisidoro/navi/blob/master/shell/navi.plugin.nu"
    click Elv "https://github.com/denisidoro/navi/blob/master/shell/navi.plugin.elv"
    click CLIParser "https://github.com/denisidoro/navi/blob/master/src/bin/main.rs"
    click CommandModules "https://github.com/denisidoro/navi/tree/master/src/commands"
    click ConfigManager "https://github.com/denisidoro/navi/tree/master/src/config"
    click Finder "https://github.com/denisidoro/navi/tree/master/src/finder"
    click ParserDeserializer "https://github.com/denisidoro/navi/blob/master/src/parser.rs"
    click DataStructures "https://github.com/denisidoro/navi/tree/master/src/structures"
    click CommonUtilities "https://github.com/denisidoro/navi/tree/master/src/common"
    click ExternalClients "https://github.com/denisidoro/navi/tree/master/src/clients"
    click FuzzyIntegration "https://github.com/denisidoro/navi/blob/master/src/common/terminal.rs"
    click Scripts "https://github.com/denisidoro/navi/tree/master/scripts/install"
    click Docs "https://github.com/denisidoro/navi/tree/master/docs/"
    click Tests "https://github.com/denisidoro/navi/tree/master/tests/"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef core fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
```
