# astronvim/template architecture

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

- Interactive diagram: https://gitdiagram.com/astronvim/template
- Repository: https://github.com/astronvim/template

## Overview

##### Project type and purpose
- This is a Neovim user-configuration repository built on top of AstroNvim v5.
- Its purpose is to define and organize your editor’s behavior by using Lua modules, a plugin manager, LSP servers, treesitter parsers, formatters, and UI extensions.

##### File structure
- Top‐level files:
- .luarc.json, .neoconf.json, selene.toml, .stylua.toml – static analysis / formatting configs
- neovim.yml – plugin/version lock file (used by lazy setup)
- README.md – installation instructions
- init.lua – entry point: loads the ‘lua/’ tree
- lua/ directory:
- lazy_setup.lua – configures and invokes the lazy.nvim plugin manager
- community.lua – loads community-maintained overrides/plugins
- plugins/ – one file per plugin or plugin group (astrocore.lua, astrolsp.lua, astroui.lua, mason.lua, none-ls.lua, treesitter.lua, user.lua)
- polish.lua – final tweaks: keymaps, highlights, autocmds

##### Key insights from the README
- This is a fork-or-template repo: you clone it into ~/.config/nvim

a. Main components
- Neovim core (the host application)
- AstroNvim “framework” (external dependency, supplied via lazy.nvim)
- User configuration repo (this project)
- Plugin manager (lazy.nvim)
- Individual plugin modules (LSP config, Mason, Treesitter, UI plugins, formatters)
- Formatters/Linters (null-ls via none-ls.lua)
- External language servers & parsers (installed by Mason)
b. Relationships & interactions
1. Neovim starts → loads init.lua
2. init.lua → calls lua/lazy_setup.lua
3. lazy_setup.lua → invokes lazy.nvim, which:
- fetches AstroNvim core (and community overrides)
- loads each file in lua/plugins/ on demand (lazy load by event or command)
4. Plugin modules configure:
– LSP servers via astrolsp.lua & mason.lua
– Treesitter via treesitter.lua
– Formatters/linters via none-ls.lua
– UI via astroui.lua & astrocore.lua
– user.lua for your custom plugin additions
5. Once all plugins are set up, polish.lua runs to apply final keymaps, autocmds, highlights
c. Architectural patterns
- Modular, plugin-driven configuration
- Event-based lazy loading (minimizes startup time)
- Clear separation between “framework” (AstroNvim), “manager” (lazy.nvim), and “user config”
d. Key technologies
- Lua (configuration language)
- lazy.nvim (plugin manager)
- AstroNvim core (framework)
- mason.nvim (LSP/formatter installer)
- null-ls (formatters/linters)
- nvim-treesitter (syntax parsing)
- stylua, selene (format/lint for this repo)

##### Detail
- That init.lua is the entrypoint, lazy_setup.lua is the orchestrator, plugin files each configure a distinct part of the editor, and polish.lua finalizes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host
    subgraph "Host Application"
        Neovim["Neovim Core"]:::host
        init["init.lua"]:::host
    end

    %% Framework
    subgraph "Framework"
        Astro["AstroNvim Framework"]:::framework
    end

    %% Manager
    subgraph "Plugin Manager"
        lazy["lazy.nvim Plugin Manager"]:::manager
    end

    %% User Config
    subgraph "User Configuration"
        community["community.lua"]:::userconfig
        astrocore["astrocore.lua"]:::userconfig
        astrolsp["astrolsp.lua"]:::userconfig
        masonCfg["mason.lua"]:::userconfig
        treesitter["treesitter.lua"]:::userconfig
        none_ls["none-ls.lua"]:::userconfig
        astroui["astroui.lua"]:::userconfig
        usermod["user.lua"]:::userconfig
        polish["polish.lua"]:::userconfig
    end

    %% External Services
    subgraph "External Services"
        LSP["LSP Servers & Formatters"]:::external
        Parsers["Treesitter Parsers"]:::external
    end

    %% Static Configs & Docs
    subgraph "Repository Files"
        lock["neovim.yml"]:::config
        README["README.md"]:::config
        luarc[".luarc.json"]:::config
        neoconf[".neoconf.json"]:::config
        selene["selene.toml"]:::config
        stylua[".stylua.toml"]:::config
    end

    %% Connections
    Neovim -->|"loads"| init
    init -->|"on start"| lazy
    lazy -->|"fetches & loads"| Astro
    lazy -->|"loads community overrides"| community
    lazy -->|"lazy-loads plugins"| astrocore
    lazy -->|"lazy-loads plugins"| astrolsp
    lazy -->|"lazy-loads plugins"| masonCfg
    lazy -->|"lazy-loads plugins"| treesitter
    lazy -->|"lazy-loads plugins"| none_ls
    lazy -->|"lazy-loads plugins"| astroui
    lazy -->|"lazy-loads plugins"| usermod
    astrocore -->|"configures UI core"| Astro
    astrolsp -->|"configures LSP via Astro"| Astro
    masonCfg -->|"installs servers"| LSP
    treesitter -->|"configures parsers"| Parsers
    none_ls -->|"configures null-ls"| LSP
    astroui -->|"configures UI enhancements"| Astro
    usermod -->|"additional plugins"| lazy
    polish -->|"final tweaks"| Neovim

    masonCfg --> LSP
    treesitter --> Parsers

    %% Click Events
    click init "https://github.com/astronvim/template/blob/main/init.lua"
    click lazy "https://github.com/astronvim/template/blob/main/lua/lazy_setup.lua"
    click community "https://github.com/astronvim/template/blob/main/lua/community.lua"
    click astrocore "https://github.com/astronvim/template/blob/main/lua/plugins/astrocore.lua"
    click astrolsp "https://github.com/astronvim/template/blob/main/lua/plugins/astrolsp.lua"
    click masonCfg "https://github.com/astronvim/template/blob/main/lua/plugins/mason.lua"
    click treesitter "https://github.com/astronvim/template/blob/main/lua/plugins/treesitter.lua"
    click none_ls "https://github.com/astronvim/template/blob/main/lua/plugins/none-ls.lua"
    click astroui "https://github.com/astronvim/template/blob/main/lua/plugins/astroui.lua"
    click usermod "https://github.com/astronvim/template/blob/main/lua/plugins/user.lua"
    click polish "https://github.com/astronvim/template/blob/main/lua/polish.lua"
    click lock "https://github.com/astronvim/template/blob/main/neovim.yml"
    click README "https://github.com/astronvim/template/blob/main/README.md"
    click luarc "https://github.com/astronvim/template/blob/main/.luarc.json"
    click neoconf "https://github.com/astronvim/template/blob/main/.neoconf.json"
    click selene "https://github.com/astronvim/template/blob/main/selene.toml"
    click stylua "https://github.com/astronvim/template/blob/main/.stylua.toml"

    %% Styles
    classDef host fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef framework fill:#ffa500,stroke:#333,stroke-width:1px
    classDef manager fill:#9370db,stroke:#333,stroke-width:1px
    classDef userconfig fill:#87ceeb,stroke:#333,stroke-width:1px
    classDef external fill:#98fb98,stroke:#333,stroke-width:1px
    classDef config fill:#f0e68c,stroke:#333,stroke-width:1px
```
