# tencent/luahelper architecture

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

- Interactive diagram: https://gitdiagram.com/tencent/luahelper
- Repository: https://github.com/tencent/luahelper

## Overview

##### Project Type and Purpose
- LuaHelper is a two-part tooling ecosystem:
a. A Visual Studio Code extension (luahelper-vscode) written in TypeScript that provides editor UI, language client, and debug adapter.
b. A standalone Language Server Protocol (LSP) server (luahelper-lsp) written in Go that performs parsing, semantic analysis, formatting, and diagnostics.
- It implements Microsoft’s Language Server Protocol for Lua editing features (completion, go-to-definition, hover, references) and integrates a Debug Adapter Protocol (DAP) debug adapter based on LuaPanda.

##### File-Structure Analysis
- Top level: docs, images, README, CI configs.
- luahelper-lsp: Go module containing:
- main.go — entry point for the LSP server
- langserver/ — LSP protocol handlers (initialize, textDocument, workspace, common utilities, file management)
- langserver/check/ — code analysis packages (lexer, parser, AST annotation, semantic checks, caches)
- langserver/diagnostics_manager.go — orchestrates error reporting
- testdata/ — sample Lua projects for unit tests
- luahelper-vscode: VSCode extension containing:
- src/ — TypeScript code for language client, debug adapter, and extension activation
- debug/ — DAP adapter implementation (debugAdapter.ts, luaDebugRuntime.ts)
- client/ and server/ — shipped binaries (lualsp.exe, luaformat, luasocket plugins) for different OSes
- build/ — packaging scripts

##### Key README Insights
- Emphasizes cross-platform support, coroutine-based real-time analysis, large-project scalability, and integration of external libs:
- luago-book for AST
- LuaFormatter (C++)
- LuaPanda for debugging

a. Main Components
- VSCode Editor & Extension Host (Frontend UI)
- Language Client (TS)
- Debug Adapter (TS)
- LSP Server Process (Go)
- Lua Analysis Engine (lexer/parser/AST/semantic modules)
- External Libraries (luago AST generator, LuaFormatter, LuaPanda debug runtime)
- Workspace File System & Configuration (jsonconfig, user settings)
b. Relationships & Data Flows
1. User edits Lua → VSCode UI → Language Client sends JSON-RPC LSP requests (over stdio or TCP) → LSP Server
2. LSP Server parses files, runs checks, formatting via external libs, returns diagnostics/responses → Language Client → UI
3. On debug start → VSCode UI triggers Debug Adapter → spawns Lua process with LuaPanda.lua injected → communicates via DAP → VSCode UI
c. Architectural Patterns
- Client-Server (LSP over JSON-RPC)
- Adapter (Debug Adapter Protocol)
- Modular Go packages (analysis, annotation, common utilities)
- VSCode extension activation events & command registration
d. Core Technologies
- Go (LSP server)
- TypeScript (VSCode extension)
- JSON-RPC, LSP & DAP protocols
- C++ LuaFormatter
- LuaPanda (Lua debug runtime)

##### Detailed Capture
- Testdata as supporting unit-test artifact.
- Build scripts packaging VSCode extension and compiled LSP binaries for each OS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "VSCode Extension (Frontend UI)"
        direction TB
        EditorUI["VSCode Extension Frontend<br/>(Extension Host UI)"]:::frontend
        LangClient["Language Client"]:::frontend
        DebugAdapter["Debug Adapter"]:::frontend
        DataProcessor["Data Processor"]:::frontend
        BreakPointMgr["Breakpoint Manager"]:::frontend
    end

    %% Backend Layer
    subgraph "LSP Server (Backend)"
        direction TB
        LSPServer["LSP Server Process"]:::server
        subgraph "Language Server"
            direction TB
            ProtocolHandlers["LSP Protocol Handlers"]:::server
            FileMgr["File Management Module"]:::server
            DiagnosticsMgr["Diagnostics Manager"]:::server
            subgraph "Lua Analysis Engine"
                direction TB
                SemanticChecks["Semantic Checks & Annotation"]:::server
                Compiler["Lexer/Parser/AST Generator"]:::server
                CommonUtils["Common Utilities & Caching"]:::server
            end
        end
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        ASTGen["luago AST Generator"]:::external
        Formatter["LuaFormatter (C++)"]:::external
        LuaPandaRuntime["LuaPanda Debug Runtime"]:::external
    end

    %% File System & Config
    subgraph "File System & Configuration"
        direction TB
        WorkspaceFS["Workspace FS & Configuration"]:::fs
        TestData["Test Data (Unit Tests)"]:::fs
    end

    %% Connections
    EditorUI -->|"sends edits"| LangClient
    LangClient -->|"JSON-RPC (LSP)"| LSPServer
    LSPServer --> ProtocolHandlers
    ProtocolHandlers --> FileMgr
    ProtocolHandlers --> DiagnosticsMgr
    DiagnosticsMgr --> SemanticChecks
    SemanticChecks --> Compiler
    SemanticChecks --> CommonUtils
    Compiler --> CommonUtils
    SemanticChecks --> ASTGen
    Compiler --> ASTGen
    SemanticChecks --> Formatter
    Formatter -->|"format calls"| LSPServer
    EditorUI -.->|"invoke debug"| DebugAdapter
    DebugAdapter --> DataProcessor
    DebugAdapter --> BreakPointMgr
    DebugAdapter --> LuaPandaRuntime
    WorkspaceFS --> LangClient
    WorkspaceFS --> LSPServer
    LSPServer --> TestData

    %% Click Events
    click EditorUI "https://github.com/tencent/luahelper/blob/master/luahelper-vscode/src/extension.ts"
    click LangClient "https://github.com/tencent/luahelper/tree/master/luahelper-vscode/src"
    click DebugAdapter "https://github.com/tencent/luahelper/blob/master/luahelper-vscode/src/debug/debugAdapter.ts"
    click DataProcessor "https://github.com/tencent/luahelper/blob/master/luahelper-vscode/src/debug/dataProcessor.ts"
    click BreakPointMgr "https://github.com/tencent/luahelper/blob/master/luahelper-vscode/src/debug/breakPoint.ts"
    click LSPServer "https://github.com/tencent/luahelper/blob/master/luahelper-lsp/main.go"
    click ProtocolHandlers "https://github.com/tencent/luahelper/tree/master/luahelper-lsp/langserver"
    click DiagnosticsMgr "https://github.com/tencent/luahelper/blob/master/luahelper-lsp/langserver/diagnostics_manager.go"
    click FileMgr "https://github.com/tencent/luahelper/blob/master/luahelper-lsp/langserver/filefolder/filefolder.go"
    click SemanticChecks "https://github.com/tencent/luahelper/tree/master/luahelper-lsp/langserver/check/analysis"
    click Compiler "https://github.com/tencent/luahelper/tree/master/luahelper-lsp/langserver/check/compiler/lexer"
    click CommonUtils "https://github.com/tencent/luahelper/tree/master/luahelper-lsp/langserver/check/common"
    click TestData "https://github.com/tencent/luahelper/tree/master/luahelper-lsp/testdata"
    click LuaPandaRuntime "https://github.com/tencent/luahelper/blob/master/luahelper-vscode/debugger/LuaPanda.lua"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#006bb3,color:#000
    classDef server fill:#d5f5d5,stroke:#28a745,color:#000
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef fs fill:#f0f0f0,stroke:#888888,color:#000
```
