# nvim-neorg/neorg architecture

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

- Interactive diagram: https://gitdiagram.com/nvim-neorg/neorg
- Repository: https://github.com/nvim-neorg/neorg

## Overview

##### Main Project Type and Purpose
- Project type: Neovim plugin.
- Purpose: To provide an integrated and extensible environment for structured note taking, task management, and documentation—all built atop a single, expressive plaintext file format.
- Key insight: The README emphasizes extensibility (via modules), integration with various external tools (like nvim-treesitter, completion systems, etc.), and complex configuration including a dedicated configuration API.

##### File Structure
- Core Code (“lua/neorg”):
– Contains core logic like configuration (lua/neorg/core/config.lua), logging, initialization, and utility functions.
– The “modules” subdirectory (lua/neorg/modules) is subdivided into numerous components (clipboard, concealer, completion, date/time handling, etc.) which point to a modular, plug-and-play design.
- External Interfaces:
– “lua/neorg/external” and integrations for treesitter, nvim-cmp, and others highlight how Neorg communicates with external Neovim plugin systems.
- Auxiliary Components:
– “docgen” to generate documentation.
– “queries” for treesitter or language-specific queries.
– “res” for assets including logos and additional resources.
- Supporting Config & CI:
– The presence of several GitHub Actions workflows (.github/workflows) and Nix files indicates CI/CD, testing, and reproducible builds.
– Files like Makefile, rockspec, and nix configuration indicate careful control over dependencies and the build environment.

##### Main Components
a. Neorg Core Engine:
– Central module for initialization (lua/neorg/core/init.lua)
– Configuration and logging (lua/neorg/core/config.lua and log.lua)
– Callback and module loader systems (callbacks.lua and modules.lua)
b. Modular Functional Units:
– UI Components: Concealer, presenter, and selection popups (located in lua/neorg/modules/core/ui and their submodules).
– File System & Storage: Modules handling file system operations (fs, storage, scanner).
– Integration Modules: Separate submodules for integrations with other Neovim systems (treesitter integration, nvim-cmp, etc.).
– Domain-Specific Functionalities: Journal, export (markdown), task management (todo-introspector), and even LaTeX rendering support.
c. Documentation & Auxiliary Tools:
– Documentation generation through the “docgen” folder.
– Query files and cheatsheets under “doc” and “queries.”
d. Infrastructure and DevOps:
– CI/CD and testing pipelines defined in .github/workflows.
– Dependency and package management via rocks, nix, and rockspec definitions.

##### Relationships and Data Flow
- At the center is the Core Engine, which initializes and coordinates all submodules.
- Each module (e.g., Concealer, Clipboard, Journal) plugs into this core and registers callbacks, keybinds, and configuration.
- External integrations (e.g., treesitter, completion modules) interact through well-defined interfaces provided by Neorg.
- The configuration layer manages both core and module-specific settings, establishing how the components interact.
- Documentation generation and testing/CI systems are peripheral but vital, ensuring maintainability and quality.

##### Architectural Patterns & Design Principles
- Modular design: Every functionality is isolated in separate Lua modules for maintainability.
- Separation of concerns: Clear boundaries between configuration, core logic, UI, integrations, and documentation.
- Extensibility: The design encourages plugging in new modules or modifying existing ones without impacting the core engine.
- External integration: The system uses adapters to communicate with the Neovim ecosystem and external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Neorg Core Engine"
        CORE("Neorg Core Engine"):::core
    end

    subgraph "Modules"
        subgraph "UI Components"
            UI_Concealer("UI - Concealer"):::module
            UI_Presenter("UI - Presenter"):::module
            UI_Selection("UI - Selection Popup"):::module
        end
        subgraph "File System & Storage"
            FS("File System Module"):::module
            Storage("Storage Module"):::module
            Scanner("Scanner Module"):::module
        end
        subgraph "Integration Modules"
            TS("Integration - Treesitter Adapter"):::integration
            CMP("Integration - nvim-cmp"):::integration
            COMPE("Integration - nvim-compe"):::integration
        end
        subgraph "Domain-Specific"
            Journal("Journal Module"):::domain
            ExportMD("Export (Markdown)"):::domain
            ExportCore("Export (Core)"):::domain
            Todo("Task Management (Todo Introspector)"):::domain
            LaTeX("LaTeX Renderer"):::domain
        end
    end

    subgraph "Auxiliary"
        External("External Interfaces"):::external
        subgraph "Documentation & Tools"
            DocGen("Documentation Generation (DocGen)"):::doc
            Documentation("Documentation (.norg)"):::doc
            Cheatsheet("Cheatsheet (.norg)"):::doc
        end
    end

    subgraph "DevOps & CI/CD"
        CI("CI/CD Workflows"):::ci
        Makefile("Makefile"):::ci
        NixRock("Nix & Rockspec"):::ci
    end

    %% Connections from Core Engine to all Modules and Auxiliary Components
    CORE -->|"init"| UI_Concealer
    CORE -->|"init"| UI_Presenter
    CORE -->|"init"| UI_Selection
    CORE -->|"init"| FS
    CORE -->|"init"| Storage
    CORE -->|"init"| Scanner
    CORE -->|"init"| TS
    CORE -->|"init"| CMP
    CORE -->|"init"| COMPE
    CORE -->|"init"| Journal
    CORE -->|"init"| ExportMD
    CORE -->|"init"| ExportCore
    CORE -->|"init"| Todo
    CORE -->|"init"| LaTeX
    CORE -->|"init"| External
    CORE -->|"init"| DocGen
    CORE -->|"init"| Documentation
    CORE -->|"init"| Cheatsheet
    CORE -->|"init"| CI
    CORE -->|"init"| Makefile
    CORE -->|"init"| NixRock

    %% Click Events
    click CORE "https://github.com/nvim-neorg/neorg/tree/main/lua/neorg/core"
    click UI_Concealer "https://github.com/nvim-neorg/neorg/tree/main/lua/neorg/modules/core/concealer"
    click UI_Presenter "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/presenter/module.lua"
    click UI_Selection "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/ui/selection_popup/module.lua"
    click FS "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/fs/module.lua"
    click Storage "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/storage/module.lua"
    click Scanner "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/scanner/module.lua"
    click TS "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/integrations/treesitter/module.lua"
    click CMP "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/integrations/nvim-cmp/module.lua"
    click COMPE "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/integrations/nvim-compe/module.lua"
    click Journal "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/journal/module.lua"
    click ExportMD "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/export/markdown/module.lua"
    click ExportCore "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/export/module.lua"
    click Todo "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/todo-introspector/module.lua"
    click LaTeX "https://github.com/nvim-neorg/neorg/blob/main/lua/neorg/modules/core/latex/renderer/module.lua"
    click External "https://github.com/nvim-neorg/neorg/tree/main/lua/neorg/external"
    click DocGen "https://github.com/nvim-neorg/neorg/tree/main/docgen"
    click Documentation "https://github.com/nvim-neorg/neorg/blob/main/doc/neorg.norg"
    click Cheatsheet "https://github.com/nvim-neorg/neorg/blob/main/doc/cheatsheet.norg"
    click CI "https://github.com/nvim-neorg/neorg/tree/main/.github/workflows"
    click Makefile "https://github.com/nvim-neorg/neorg/tree/main/Makefile"
    click NixRock "https://github.com/nvim-neorg/neorg/tree/main/nix/"

    %% Styles
    classDef core fill:#f9d3a2,stroke:#333,stroke-width:2px;
    classDef module fill:#bae1ff,stroke:#333,stroke-width:2px;
    classDef integration fill:#c1f0c1,stroke:#333,stroke-width:2px;
    classDef domain fill:#ffc1c1,stroke:#333,stroke-width:2px;
    classDef external fill:#fceabb,stroke:#333,stroke-width:2px;
    classDef doc fill:#d4a5a5,stroke:#333,stroke-width:2px;
    classDef ci fill:#d4e157,stroke:#333,stroke-width:2px;
```
