# pandalanax/panda-nix-vim architecture

> Architecture diagram of the GitHub repository pandalanax/panda-nix-vim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pandalanax/panda-nix-vim
- Repository: https://github.com/pandalanax/panda-nix-vim

## Overview

##### What this project is (type + purpose)

This repo is **not an “application” with runtime services** (no backend, DB, frontend). It’s a **declarative Neovim distribution/configuration** built using **Nix** and specifically **nixvim** (from nix-community).

**Purpose:** provide a reproducible Neovim setup (plugins + options + keymaps + LSP, etc.) that can be executed via:

- `nix run github:pandalanax/panda-nix-vim`

So the “system” you’re diagramming is essentially:

- **Nix Flake packaging** → builds a **Neovim + plugin ecosystem** → user runs it on their machine
- The internal architecture is a set of **Nix modules** under `config/` that compose into a final nixvim configuration.

##### Top-level (packaging/entry points)
- `flake.nix` / `flake.lock`
- **Primary entry point**. Defines flake outputs (likely a runnable app) and pins dependencies in `flake.lock`.
- `README.md`, `LICENSE`
- `pics/`
- Documentation asset (not architectural).
- `config/`
- The real “modules” of the system: each `.nix` file is a configuration slice.

##### `config/` (composition-based modular architecture)
- `config/default.nix`
- Central composition point: imports/aggregates the other module files.
- Individual config modules, each mapping to a Neovim subsystem/plugin:
- `options.nix` (core Neovim options)
- `keymaps.nix` (keybindings)
- `lsp.nix` (LSP configuration)
- `treesitter.nix` (syntax/parsing)
- `cmp.nix` (completion)
- `conform.nix` (formatting)
- `git.nix`, `gitsigns.nix` (git integration)
- `telescope.nix`, `telescope-project.nix` (search/project navigation)
- `comment.nix`, `surround.nix`, `auto-pair.nix` (editing UX)
- `oil.nix` (file explorer)
- `fidget.nix` (LSP UI/status)
- `tmux-navigator.nix` (tmux integration)
- `alpha.nix` (dashboard/start screen)
- `extraConfig.nix` (escape hatch for custom config)

**Architectural pattern:** “modular Nix configuration composed via imports” (very similar to NixOS module composition).

##### Resulting runnable Neovim package (the output artifact)

**Key interactions:**
- User triggers `nix run` → Nix evaluates `flake.nix`
- Nix uses `flake.lock` to fetch exact versions
- nixvim consumes the configuration modules → produces a configured Neovim derivation
- Output is executed on the user machine

This is the “system context” view.

##### Configuration composition layer (inner architecture)
**Main components to show:**
- `config/default.nix` as the **composition root**
- Each `config/*.nix` module as a **child module**
- Modules by domain:
- Editor features: `treesitter.nix`, `cmp.nix`, `conform.nix`
- Navigation: `telescope.nix`, `telescope-project.nix`, `oil.nix`
- Git: `git.nix`, `gitsigns.nix`
- UX: `alpha.nix`, `fidget.nix`
- Editing helpers: `comment.nix`, `surround.nix`, `auto-pair.nix`
- Integration: `tmux-navigator.nix`
- LSP: `lsp.nix` (central feature module)

**Key interactions:**
- `default.nix` imports modules → merged into final nixvim config
- Several modules implicitly depend on others (conceptually, not via direct imports):
- `lsp.nix` + `cmp.nix` + `fidget.nix` (LSP experience)
- `treesitter.nix` boosts syntax support used broadly
- `conform.nix` interacts with language tooling and may be triggered via keymaps
- `telescope*.nix` depends on keymaps/options for UX

##### Build/evaluation flow (Nix-time)
- `User` → `nix run` → `flake.nix`
- `flake.nix` → `flake.lock` (dependency pinning / fetch)
- `flake.nix` → `nixvim` (library/module system)
- `flake.nix` → `config/default.nix`
- `config/default.nix` → `config/*.nix` modules
- `nixvim + merged config` → `Neovim package (derivation)`
- `Neovim package` → runs on `User machine`

##### Runtime interaction flow (Neovim-time)
- `Neovim runtime` ↔ `Plugins` (configured by modules)
- LSP servers (for `lsp.nix`)
- formatters/linters (for `conform.nix`)
- git CLI/repo (for `git.nix`, `gitsigns.nix`)
- tmux (for `tmux-navigator.nix`)

Even if those tools aren’t in the repo, they are part of the **operational architecture** of this configuration.

##### Important architectural principles to highlight (specific to this repo)

- **Reproducibility & immutability:** `flake.lock` pins everything.
- **Declarative configuration:** behavior is defined in `.nix` modules, not imperative setup scripts.
- **Separation of concerns:** each plugin/system has a dedicated module file.
- **Composition root:** `config/default.nix` is the hub that assembles the final configuration.
- **Extensibility workflow:** adding a new config file requires updating `config/default.nix` (explicitly stated in README).

##### “Don’t overthink it” but be detailed: what “detailed” means here

Detail is achieved by:
- Treating **each `config/*.nix` file as its own component**
- Showing **the composition root (`config/default.nix`) explicitly**
- Showing **the flake boundary**: everything flows from `flake.nix`
- Including **external runtime integrations** (LSP servers/formatters/tmux/git) as environment dependencies

- Open `config/default.nix` and mirror the **exact import list and any ordering**.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: System Context
  %% =========================
  subgraph "Diagram 1 — System Context (Packaging / Build / Execution)"
    direction TB

    U["User / Developer"]:::user
    M["User machine"]:::user

    NIX["Nix CLI\n\"nix run github:pandalanax/panda-nix-vim\""]:::external
    subgraph "This Repo (Nix Flake)"
      direction TB
      FLAKE["flake.nix\nFlake outputs (app/package)"]:::repo
      LOCK["flake.lock\nPinned dependencies (reproducibility)"]:::lock
      CFGDIR["config/\nNixvim module directory"]:::repo
      CFGROOT["config/default.nix\nComposition root (imports modules)"]:::repo
    end

    NIXVIM["nixvim (nix-community)\nModule framework"]:::external
    OUT["Configured Neovim package\n(Nix derivation in Nix store)"]:::artifact
    NVRT["Neovim runtime\n(launched by nix run)"]:::external

    subgraph "Runtime Environment (External Tools)"
      direction TB
      LSPTOOLS["LSP servers\n(language tooling)"]:::tooling
      FORMATTERS["Formatters / Linters"]:::tooling
      GITTOOLS["Git CLI + Repository"]:::env
      TMUX["tmux"]:::env
    end

    U -->|"invokes"| NIX
    NIX -->|"evaluates"| FLAKE
    FLAKE -->|"uses_pins"| LOCK
    FLAKE -->|"loads_modules"| CFGROOT
    CFGDIR -->|"contains"| CFGROOT
    FLAKE -->|"depends_on"| NIXVIM
    CFGROOT -->|"module_config"| NIXVIM
    NIXVIM -->|"builds"| OUT
    OUT -->|"executes_on"| M
    M -->|"runs"| NVRT

    NVRT <-->|"LSP_protocol"| LSPTOOLS
    NVRT <-->|"format_on_save/command"| FORMATTERS
    NVRT <-->|"git_commands"| GITTOOLS
    NVRT <-->|"navigation_integration"| TMUX

    NOTE1["Principles:\n- Reproducible: flake.lock pins versions\n- Declarative: all behavior in .nix modules\n- Extensible: add module + import in config/default.nix"]:::note
    FLAKE -.->|"guides"| NOTE1
  end

  %% ==========================================
  %% Diagram 2: Configuration Composition (Nix)
  %% ==========================================
  subgraph "Diagram 2 — Configuration Composition (nixvim module architecture)"
    direction TB

    ROOT["config/default.nix\nComposition root"]:::repo
    MERGED["Merged nixvim configuration\n(result of module imports)"]:::artifact
    BUILD["nixvim builds derivation\n(Configured Neovim)"]:::external

    ROOT -->|"imports/aggregates"| MERGED
    MERGED -->|"fed_into"| BUILD

    subgraph "Core"
      direction TB
      OPT["config/options.nix\nCore Neovim options"]:::repo
      KEY["config/keymaps.nix\nKeybindings"]:::repo
      COL["config/colors.nix\nTheme / colorscheme"]:::repo
      EXTRA["config/extraConfig.nix\nEscape hatch / custom config"]:::repo
    end

    subgraph "LSP"
      direction TB
      LSP["config/lsp.nix\nLSP client + servers config"]:::repo
      FIDGET["config/fidget.nix\nLSP UI / status"]:::repo
      CMP["config/cmp.nix\nCompletion engine (nvim-cmp)"]:::repo
    end

    subgraph "Editor Features"
      direction TB
      TS["config/treesitter.nix\nSyntax trees / parsers"]:::repo
      CONF["config/conform.nix\nFormatting pipeline"]:::repo
    end

    subgraph "Navigation"
      direction TB
      TEL["config/telescope.nix\nFuzzy finder / search"]:::repo
      TELPROJ["config/telescope-project.nix\nProject navigation"]:::repo
      OIL["config/oil.nix\nFile explorer"]:::repo
    end

    subgraph "Git"
      direction TB
      GIT["config/git.nix\nGit integration"]:::repo
      GSIG["config/gitsigns.nix\nGit signs"]:::repo
    end

    subgraph "Editing Helpers"
      direction TB
      COMM["config/comment.nix\nComment helper"]:::repo
      SURR["config/surround.nix\nSurround helper"]:::repo
      PAIR["config/auto-pair.nix\nAuto pairs"]:::repo
    end

    subgraph "UX"
      direction TB
      ALPHA["config/alpha.nix\nDashboard / start screen"]:::repo
    end

    subgraph "Integration"
      direction TB
      TMUXNAV["config/tmux-navigator.nix\ntmux navigation integration"]:::repo
    end

    %% Imports from composition root
    ROOT -->|"imports"| OPT
    ROOT -->|"imports"| KEY
    ROOT -->|"imports"| COL
    ROOT -->|"imports"| EXTRA

    ROOT -->|"imports"| LSP
    ROOT -->|"imports"| FIDGET
    ROOT -->|"imports"| CMP

    ROOT -->|"imports"| TS
    ROOT -->|"imports"| CONF

    ROOT -->|"imports"| TEL
    ROOT -->|"imports"| TELPROJ
    ROOT -->|"imports"| OIL

    ROOT -->|"imports"| GIT
    ROOT -->|"imports"| GSIG

    ROOT -->|"imports"| COMM
    ROOT -->|"imports"| SURR
    ROOT -->|"imports"| PAIR

    ROOT -->|"imports"| ALPHA
    ROOT -->|"imports"| TMUXNAV

    %% Conceptual (implicit) dependencies / interactions
    KEY -.->|"triggers"| TEL
    KEY -.->|"triggers"| TELPROJ
    KEY -.->|"triggers"| CONF
    LSP -.->|"completes_via"| CMP
    LSP -.->|"status_via"| FIDGET
    TS -.->|"enhances"| LSP
    TS -.->|"enhances"| CMP
  end

  %% =========================
  %% Repo Docs / Assets
  %% =========================
  subgraph "Documentation"
    direction TB
    README["README.md\nUsage + extensibility workflow"]:::doc
    PICS["pics/\nDocumentation assets"]:::doc
  end

  README -.->|"documents"| FLAKE
  README -.->|"documents"| CFGROOT
  PICS -.->|"illustrates"| README

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click FLAKE "https://github.com/pandalanax/panda-nix-vim/blob/main/flake.nix"
  click LOCK "https://github.com/pandalanax/panda-nix-vim/blob/main/flake.lock"
  click CFGDIR "https://github.com/pandalanax/panda-nix-vim/tree/main/config/"
  click CFGROOT "https://github.com/pandalanax/panda-nix-vim/blob/main/config/default.nix"
  click OPT "https://github.com/pandalanax/panda-nix-vim/blob/main/config/options.nix"
  click KEY "https://github.com/pandalanax/panda-nix-vim/blob/main/config/keymaps.nix"
  click COL "https://github.com/pandalanax/panda-nix-vim/blob/main/config/colors.nix"
  click LSP "https://github.com/pandalanax/panda-nix-vim/blob/main/config/lsp.nix"
  click TS "https://github.com/pandalanax/panda-nix-vim/blob/main/config/treesitter.nix"
  click CMP "https://github.com/pandalanax/panda-nix-vim/blob/main/config/cmp.nix"
  click CONF "https://github.com/pandalanax/panda-nix-vim/blob/main/config/conform.nix"
  click GIT "https://github.com/pandalanax/panda-nix-vim/blob/main/config/git.nix"
  click GSIG "https://github.com/pandalanax/panda-nix-vim/blob/main/config/gitsigns.nix"
  click TEL "https://github.com/pandalanax/panda-nix-vim/blob/main/config/telescope.nix"
  click TELPROJ "https://github.com/pandalanax/panda-nix-vim/blob/main/config/telescope-project.nix"
  click COMM "https://github.com/pandalanax/panda-nix-vim/blob/main/config/comment.nix"
  click SURR "https://github.com/pandalanax/panda-nix-vim/blob/main/config/surround.nix"
  click PAIR "https://github.com/pandalanax/panda-nix-vim/blob/main/config/auto-pair.nix"
  click OIL "https://github.com/pandalanax/panda-nix-vim/blob/main/config/oil.nix"
  click FIDGET "https://github.com/pandalanax/panda-nix-vim/blob/main/config/fidget.nix"
  click TMUXNAV "https://github.com/pandalanax/panda-nix-vim/blob/main/config/tmux-navigator.nix"
  click ALPHA "https://github.com/pandalanax/panda-nix-vim/blob/main/config/alpha.nix"
  click EXTRA "https://github.com/pandalanax/panda-nix-vim/blob/main/config/extraConfig.nix"
  click README "https://github.com/pandalanax/panda-nix-vim/blob/main/README.md"
  click PICS "https://github.com/pandalanax/panda-nix-vim/tree/main/pics/"

  %% =========================
  %% Styles
  %% =========================
  classDef repo fill:#d6ecff,stroke:#2b6cb0,stroke-width:1.5px,color:#0b2540
  classDef lock fill:#fde68a,stroke:#b45309,stroke-width:1.5px,color:#3b2f07
  classDef external fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
  classDef artifact fill:#ddd6fe,stroke:#5b21b6,stroke-width:1.5px,color:#1f1147
  classDef user fill:#d1fae5,stroke:#047857,stroke-width:1.5px,color:#064e3b
  classDef env fill:#bbf7d0,stroke:#166534,stroke-width:1.5px,color:#052e16
  classDef tooling fill:#fed7aa,stroke:#c2410c,stroke-width:1.5px,color:#431407
  classDef doc fill:#fce7f3,stroke:#9d174d,stroke-width:1.5px,color:#500724
  classDef note fill:#fff7ed,stroke:#9a3412,stroke-width:1.5px,color:#431407,stroke-dasharray: 4 3
```
