# emacs-tree-sitter/elisp-tree-sitter architecture

> Architecture diagram of the GitHub repository emacs-tree-sitter/elisp-tree-sitter, 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/emacs-tree-sitter/elisp-tree-sitter
- Repository: https://github.com/emacs-tree-sitter/elisp-tree-sitter

## Overview

##### Main Components
- Core Dynamic Module: The “core” directory contains Rust code (with files such as lib.rs, parser.rs, etc.) that provides the underlying tree-sitter dynamic module. Its role is to perform the actual parsing work and offer an API for tree analysis.
- Emacs Lisp Integration: The “lisp” directory holds the ELisp files that bind the core dynamic module to Emacs, enabling features like improved syntax highlighting, code folding, and structural editing.
- Language Grammars: The “langs” directory provides support for handling language-specific aspects (such as grammar sources and scripts to compile them), which work in conjunction with tree-sitter.
- Build, Test, and Dev Automation: The “bin” directory contains scripts to set up the environment, build the project, run tests, and package the modules. The continuous integration configuration in “.github” further supports these activities.
- Documentation and UI: The “doc” directory includes site templates, static assets, and configuration files that drive documentation (and possibly generate a website for the project).

##### Relationships and Interactions
- The language-specific compiler and configuration scripts in “langs” interact with both the dynamic module and the build automation scripts. Represent “langs” as a separate block that feeds into the build system and possibly interfaces indirectly with “core” to update or compile grammars.
- The utility scripts in “bin” (for setup, build, test, package, etc.) serve as an orchestration layer ensuring that the modules are built, packaged, and tested correctly. Connect “bin” to both “core” and “lisp” as well as the “langs” component to show this orchestration.
- The “.github” folder provides CI/CD workflows that might trigger build and test processes. Indicate external systems (like GitHub Actions) that interact with the repository’s build and test lifecycle.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project clearly separates core parsing functionality (in Rust), Emacs-specific binding (in Lisp), language grammar manipulation (in langs), and automation/testing (in bin & GitHub workflows).
- Plugin/Extension Model: By allowing language grammars and dynamic module integration, the system is designed to be extensible and modular.
- Build & Test Automation: A comprehensive set of scripts and CI workflows shows practicality in continuous integration and deployment.

##### Technologies & Frameworks
- Emacs (with dynamic module support) – main user interface.
- Rust (for the “core” dynamic module).
- NodeJS and tree-sitter CLI (as mentioned in the README for generating language grammars).
- Emacs Lisp – provides the binding and integration on the Emacs side.
- CI/CD pipelines (through GitHub Actions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    E["Emacs Environment"]:::external

    %% Runtime Integration Layer
    subgraph "Runtime Integration"
        L["Emacs Lisp Binding (ELisp)"]:::elisp
        C["Dynamic Module (Rust Core - Tree-sitter)"]:::rust
    end

    %% Language Support Layer
    subgraph "Language Support"
        G["Language Grammars"]:::langs
    end

    %% Build & Automation Layer
    subgraph "Build & Automation"
        B["Build, Test, and Dev Scripts"]:::build
        CI["CI/CD (GitHub Actions)"]:::ci
    end

    %% Documentation Layer
    D["Documentation & UI"]:::doc

    %% Connections
    E -->|"Interface"| L
    L -->|"API_Calls"| C
    G -.->|"GrammarExtension"| C
    B -->|"Build_Process"| C
    B -->|"Build_Process"| L
    B -->|"Build_Process"| G
    CI -->|"Triggers"| B
    D -->|"Covers"| L
    D -->|"Covers"| C
    D -->|"Covers"| G

    %% Click Events
    click C "https://github.com/emacs-tree-sitter/elisp-tree-sitter/tree/master/core/"
    click L "https://github.com/emacs-tree-sitter/elisp-tree-sitter/tree/master/lisp/"
    click G "https://github.com/emacs-tree-sitter/elisp-tree-sitter/tree/master/langs/"
    click B "https://github.com/emacs-tree-sitter/elisp-tree-sitter/tree/master/bin/"
    click CI "https://github.com/emacs-tree-sitter/elisp-tree-sitter/tree/master/.github/"
    click D "https://github.com/emacs-tree-sitter/elisp-tree-sitter/tree/master/doc/"

    %% Styles
    classDef external fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef elisp fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef rust fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef langs fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef build fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef ci fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef doc fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
```
