# tpope/vim-projectionist architecture

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

- Interactive diagram: https://gitdiagram.com/tpope/vim-projectionist
- Repository: https://github.com/tpope/vim-projectionist

## Overview

##### Project type and purpose
- This is a Vim‐plugin, written in Vimscript, called “projectionist.vim.”

##### File structure
- Top‐level:
– README.markdown, CONTRIBUTING.markdown – project docs
– .github – CI/funding metadata
- autoload/
– projectionist.vim – core logic loaded on-demand via Vim’s autoload mechanism
- plugin/
– projectionist.vim – entry point, defines commands and autocommands at startup
- doc/
– projectionist.txt – help file (generated from README for :help)
- (Optional) .projections.json – user’s per‐project config (not in repo, but supported)

##### README for additional insights
- The README describes:
– “g:projectionist_heuristics” (global configuration)
– .projections.json (per-project config)
– Navigation commands (E*, A*, S*, V*, T* variants)
– Alternate file lookup, buffer‐local configuration (make, dispatch)
– Integration points (e.g., dispatch.vim, Rails/Vim plugins)

##### Main components
a. Vim Editor (host environment)
b. Plugin Manager / Package Loader
c. projectionist.vim (plugin/ – startup entrypoint)
d. projectionist#* functions (autoload/ – core logic)
e. User Configuration
- g:projectionist_heuristics (global Vimscript variable)
- .projections.json (per‐project JSON file)
f. File System (project files & directories)
g. External Integrations (optional plugins, e.g., dispatch.vim)

##### Relationships and interactions
- On Vim startup, the Package Loader sources plugin/projectionist.vim.
- That script:
– registers :E*, :A*, etc. commands
– sets up autocommands to lazily load autoload/projectionist.vim on first use
- When a projectionist command runs:
– autoload/projectionist.vim is sourced
– it reads configuration (g:projectionist_heuristics and/or .projections.json)
– it resolves globs against the File System
– generates navigation targets or boilerplate templates
– optionally invokes external tools (e.g., dispatch.vim commands)
- Results are returned to the user as new buffers, splits, etc.

##### Architectural patterns and design principles
- Vimscript “plugin + autoload” pattern for fast startup + lazy loading
- Declarative configuration (heuristics JSON) separated from code
- Command-pattern: each projection type yields a Vim command (:Ehook, :Eplugin, etc.)
- Single responsibility:
– plugin/ script = interface/registration
– autoload/ = core logic + JSON parsing + FS ops
– doc/ = user help
- Extensibility: users and other plugins can define new projection types

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    Editor["Vim Editor"]:::env
    Loader["Package Loader / Plugin Manager"]:::env
    Plugin["plugin/projectionist.vim\n(register commands)"]:::code
    Autoload["autoload/projectionist.vim\n(core logic, JSON parsing, FS ops)"]:::code
    Gvar["g:projectionist_heuristics"]:::config
    JSONcfg[".projections.json (optional)"]:::config
    FS["File System\n(project files & dirs)"]:::env
    Ext["dispatch.vim\n(optional integration)"]:::ext
    DocsHelp["doc/projectionist.txt"]:::docs
    DocReadme["README.markdown"]:::docs
    DocContrib["CONTRIBUTING.markdown"]:::docs
    CI[".github/FUNDING.yml"]:::docs
    GitIgnore[".gitignore"]:::docs

    %% Relationships
    Editor -->|"sourcing at startup"| Loader
    Loader -->|"sources plugin entrypoint"| Plugin
    Plugin -->|"register commands & autocommands"| Editor
    Plugin -->|"lazy-load on first command"| Autoload
    Autoload -->|"read configuration from"| Gvar
    Autoload -->|"read configuration from"| JSONcfg
    Autoload -->|"match globs"| FS
    Autoload -->|"generate navigation & templates"| Editor
    Autoload -->|".invoke integration"| Ext
    DocsHelp -.->|"generated from"| DocReadme

    %% Click Events
    click Plugin "https://github.com/tpope/vim-projectionist/blob/master/plugin/projectionist.vim"
    click Autoload "https://github.com/tpope/vim-projectionist/blob/master/autoload/projectionist.vim"
    click DocsHelp "https://github.com/tpope/vim-projectionist/blob/master/doc/projectionist.txt"
    click DocReadme "https://github.com/tpope/vim-projectionist/blob/master/README.markdown"
    click DocContrib "https://github.com/tpope/vim-projectionist/blob/master/CONTRIBUTING.markdown"
    click CI "https://github.com/tpope/vim-projectionist/blob/master/.github/FUNDING.yml"
    click GitIgnore "https://github.com/tpope/vim-projectionist/blob/master/.gitignore"
    click JSONcfg "https://github.com/tpope/vim-projectionist/blob/master/.projections.json"

    %% Styles
    classDef code fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef config fill:#ABEBC6,stroke:#1D8348,color:#1B2631
    classDef env fill:#F9E79F,stroke:#B7950B,color:#1B2631
    classDef docs fill:#F5CBA7,stroke:#AF601A,color:#1B2631
    classDef ext fill:#D6EAF8,stroke-dasharray: 5 5,stroke:#2874A6,color:#1B2631
```
