# polserver/vscode-escript architecture

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

- Interactive diagram: https://gitdiagram.com/polserver/vscode-escript
- Repository: https://github.com/polserver/vscode-escript

## Overview

##### Main Components

a) Client-side Components (VSCode Extension):
- Sub-components:
- Extension Activation Handler
- Debug Client
- Language Client
- Configuration Manager

b) Server-side Components:
- Sub-components:
- LSP Connection Handler
- Workspace Manager
- Documentation Downloader
- Analysis Engine

c) Native Components:
- Sub-components:
- EScript Compiler
- Completion Builder
- Definition Builder
- References Builder
- Hover Builder
- Signature Help Builder
- XML Doc Parser

d) External Components:
- POL Server (for debugging)
- Workspace Files
- Configuration Files (pol.cfg, ecompile.cfg)

##### Connection and Data Flow

- VSCode Extension → Language Server (LSP communication)
- Language Server → Native Module (compilation and analysis)
- VSCode Extension → POL Server (debugging via DAP)
- Language Server → Workspace Files (file system access)

##### Important Architectural Patterns to Highlight

a) Client-Server Architecture:
- Clear separation between extension client and language server
- LSP protocol communication

b) Native Bridge Pattern:
- How the TypeScript/JavaScript code interfaces with the C++ native module

c) Multi-process Architecture:
- Separation between:
- VSCode extension process
- Language server process
- POL server process (for debugging)

##### Additional Elements

- Supported file types (.src, .cfg)
- Key configuration options
- Memory management considerations
- Error handling flow

##### Bottom: Core Layer (Native Module)

Keep the abstraction level high enough to show the overall architecture while including enough detail to understand the key components and their interactions. Focus on showing how the language features (completion, hover, references) and debugging capabilities are implemented through the different layers of the system.

Remember to emphasize the extension's key features:
- Code completion
- Error detection
- Navigation features (go to definition, references)
- Debugging capabilities
- Formatting support

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph VSCode
        IDE[Visual Studio Code]
    end

    subgraph "VSCode Extension Client"
        EA["Extension Activation Handler"]:::client
        DC["Debug Client"]:::client
        LC["Language Client"]:::client
        CM["Configuration Manager"]:::client
    end

    subgraph "Language Server"
        LSP["LSP Connection Handler"]:::server
        WM["Workspace Manager"]:::server
        DD["Documentation Downloader"]:::server
        AE["Analysis Engine"]:::server
    end

    subgraph "Native Module"
        EC["EScript Compiler"]:::native
        CB["Completion Builder"]:::native
        DB["Definition Builder"]:::native
        RB["References Builder"]:::native
        HB["Hover Builder"]:::native
        SHB["Signature Help Builder"]:::native
        XDP["XML Doc Parser"]:::native
        LDH["LSP Document Handler"]:::native
        LWH["LSP Workspace Handler"]:::native
        EConfig["Extension Configuration"]:::native
    end

    subgraph "Debug Components"
        DA["POL Debug Adapter"]:::debug
        PS["POL Server"]:::debug
    end

    %% Connections
    IDE --> EA
    EA --> DC
    EA --> LC
    EA --> CM

    LC <--> LSP
    LSP <--> WM
    WM <--> DD
    WM <--> AE

    AE <--> EC
    EC --> CB
    EC --> DB
    EC --> RB
    EC --> HB
    EC --> SHB
    EC --> XDP
    EC <--> LDH
    EC <--> LWH
    EC <--> EConfig

    DC <--> DA
    DA <--> PS

    %% Styles
    classDef client fill:#2196F3,stroke:#1565C0,color:white
    classDef server fill:#4CAF50,stroke:#2E7D32,color:white
    classDef native fill:#FF9800,stroke:#EF6C00,color:white
    classDef debug fill:#9C27B0,stroke:#6A1B9A,color:white

    %% Click Events
    click EA "https://github.com/polserver/vscode-escript/blob/master/client/src/extension.ts"
    click DC "https://github.com/polserver/vscode-escript/blob/master/client/src/PolDebugClient.ts"
    click LSP "https://github.com/polserver/vscode-escript/blob/master/server/src/server/connection.ts"
    click WM "https://github.com/polserver/vscode-escript/blob/master/server/src/workspace/workspace.ts"
    click DD "https://github.com/polserver/vscode-escript/blob/master/server/src/workspace/DocsDownloader.ts"
    click CB "https://github.com/polserver/vscode-escript/blob/master/native/cpp/compiler/CompletionBuilder.cc"
    click DB "https://github.com/polserver/vscode-escript/blob/master/native/cpp/compiler/DefinitionBuilder.cc"
    click RB "https://github.com/polserver/vscode-escript/blob/master/native/cpp/compiler/ReferencesBuilder.cc"
    click HB "https://github.com/polserver/vscode-escript/blob/master/native/cpp/compiler/HoverBuilder.cc"
    click SHB "https://github.com/polserver/vscode-escript/blob/master/native/cpp/compiler/SignatureHelpBuilder.cc"
    click XDP "https://github.com/polserver/vscode-escript/blob/master/native/cpp/misc/XmlDocParser.cc"
    click LDH "https://github.com/polserver/vscode-escript/blob/master/native/cpp/napi/LSPDocument.cc"
    click LWH "https://github.com/polserver/vscode-escript/blob/master/native/cpp/napi/LSPWorkspace.cc"
    click EConfig "https://github.com/polserver/vscode-escript/blob/master/native/cpp/napi/ExtensionConfig.cc"
```
