# cordx56/rustowl architecture

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

- Interactive diagram: https://gitdiagram.com/cordx56/rustowl
- Repository: https://github.com/cordx56/rustowl

## Overview

##### Main Components
- Core Analysis Engine: Represented by the RustOwl’s Rust code under the “rustowl” directory. This includes the main binary (main.rs) and various modules that do the heavy lifting (e.g., analyze.rs, from_rustc.rs, core utilities, etc.).
- LSP Server Interface: The project implements an LSP server (“cargo-owlsp”) which extends the standard protocol to provide ownership and lifetime information. Indicate that this component acts as the mediator between the analysis core and editor integrations.
- CLI Tool: Notably, there is also a “cargo-owl” binary (in rustowl/src/bin/cargo-owl.rs) for command-line interactions.
- Editor Plugins: These are the integration plugins for various editors:
– VSCode Extension (found in the “vscode” directory)
– Neovim Plugin (configuration present in the “lua” and “example” directories, as well as in the provided Neovim snippet in the README)
– Emacs Package (under “emacs/rustowlsp.el”)
– Additionally, there is a plugin folder (“plugin/rustowl-auto.lua”) that appears to enhance the auto-activation or automatic behavior.
- Documentation and Specifications: The “docs” directory (including lsp-spec.md) documents the protocol and how the LSP extension works.

##### Relationships and Interactions
- The analysis engine exposes its functionality via the LSP server (cargo-owlsp) that sits between the Rust source code analysis and the editor integrations.
- The CLI tool (“cargo-owl”) can be used independently for command-line based analysis, possibly sharing many of the internal libraries with the LSP server.
- Build and release workflows (see .github/workflows) interact with these components to build, test, and package the various parts of the project.

##### Architectural Patterns and Design Principles
- Modular Separation: The separation between the analysis engine and its integrations highlights a clean modular architecture.
- Client-Server Pattern: The use of an LSP server establishes a clear client (editor plugins) and server (analysis engine) relationship.
- Extensibility: With dedicated folders for different editors, the system is designed to be extensible to a variety of environments.
- Configuration and Build Automation: GitHub workflows and configuration files (such as Cargo.toml and package.json for the VSCode extension) drive automated testing and release processes.

##### Relevant Technologies, Frameworks, or Libraries
- Rust: Core logic is implemented in Rust.
- LSP (Language Server Protocol): Used for communication between the analysis core and editor plugins.
- Cargo: Package manager and build system for the core Rust logic.
- Node.js and Yarn: For building the VSCode extension.
- Editor-specific tooling: Configurations for editors like Neovim (Lua based), Emacs (Elisp), and VSCode (TypeScript) indicate the important role these technologies play.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    U["User's Rust Source Code"]:::user

    %% Backend Components
    subgraph "Backend Components"
        Core["RustOwl Core / Analysis Engine\n(Written in Rust)"]:::backend
        LSP["LSP Server Interface\n(cargo-owlsp)"]:::lsp
        CLI["CLI Tool\n(cargo-owl)"]:::cli
    end

    %% Editor Integrations
    subgraph "Editor Integrations"
        VSCode["VSCode Extension\n(TypeScript)"]:::integration
        NeovimConfig["Neovim Plugin (Config)"]:::integration
        NeovimExample["Neovim Plugin (Example)"]:::integration
        Emacs["Emacs Package"]:::integration
        AutoPlugin["Auto-activation Plugin"]:::integration
    end

    %% Documentation & Automation
    Docs["Documentation & Specifications"]:::doc
    Build["Config & Automation\n(GitHub Workflows)"]:::build

    %% Data Flow
    U -->|"analyzed by"| Core
    CLI -->|"triggers analysis"| Core
    Core -->|"provides analysis"| LSP

    %% Editor Plugin interactions with LSP
    VSCode -->|"LSP_requests"| LSP
    NeovimConfig -->|"LSP_requests"| LSP
    NeovimExample -->|"LSP_requests"| LSP
    Emacs -->|"LSP_requests"| LSP
    AutoPlugin -->|"LSP_requests"| LSP

    LSP -->|"sends results"| VSCode
    LSP -->|"sends results"| NeovimConfig
    LSP -->|"sends results"| NeovimExample
    LSP -->|"sends results"| Emacs
    LSP -->|"sends results"| AutoPlugin

    %% Connections from Build & Docs to backend
    Build -->|"builds/tests"| Core
    Build -->|"builds/tests"| LSP
    Build -->|"builds/tests"| CLI
    Docs -->|"documents"| LSP

    %% Click Events
    click Core "https://github.com/cordx56/rustowl/tree/main/rustowl/src"
    click LSP "https://github.com/cordx56/rustowl/blob/main/rustowl/src/bin/cargo-owlsp.rs"
    click CLI "https://github.com/cordx56/rustowl/blob/main/rustowl/src/bin/cargo-owl.rs"
    click VSCode "https://github.com/cordx56/rustowl/tree/main/vscode/"
    click NeovimConfig "https://github.com/cordx56/rustowl/blob/main/lua/rustowl.lua"
    click NeovimExample "https://github.com/cordx56/rustowl/tree/main/example/"
    click Emacs "https://github.com/cordx56/rustowl/blob/main/emacs/rustowlsp.el"
    click AutoPlugin "https://github.com/cordx56/rustowl/blob/main/plugin/rustowl-auto.lua"
    click Docs "https://github.com/cordx56/rustowl/blob/main/docs/lsp-spec.md"
    click Build "https://github.com/cordx56/rustowl/tree/main/.github/workflows/"

    %% Styles
    classDef backend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef lsp fill:#90caf9,stroke:#1565c0,stroke-width:2px;
    classDef cli fill:#b2dfdb,stroke:#004d40,stroke-width:2px;
    classDef integration fill:#ffcc80,stroke:#e65100,stroke-width:2px;
    classDef doc fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef build fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef user fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
```
