Language Server Architecture

This document outlines the architecture of the Puya Language Server capability.

sequenceDiagram
  actor D as Developer
  participant IDE as IDE
  participant LC as Language Client
  participant LS as Language Server
  participant PF as Puya Frontend
  participant PB as Puya Backend
  D ->> IDE: keystroke
  D ->> IDE: vcsoperations
  IDE ->> LC: documentOpened (triggers init when not started)
  IDE ->> LC: configurationChanged (triggers reinit)
  IDE ->> LC: restartLanguageServer (triggers reinit)
  LC ->>+ LS: initialise()
  LS -->>- LC: initialised
  IDE ->> LC: documentChanged
  LC ->>+ LS: documentChanged
  LS ->>+ PF: compile(project)
  PF -->> LS: diagnostics (from parsing/AWST building errors)
  PF -->>- LS: awst
  LS ->>+ PB: compile(awst)
  PB -->>- LS: diagnostics
  LS -->>- LC: diagnostics

Algorand Python Language Server

The Python implementation of the Puya language server directly interacts with the Puya compiler components in the same Python process.

flowchart TB
    subgraph "VSCode IDE"
        Developer["Developer"]
        VSCodeExt["VSCode Extension"]
    end

    subgraph "Python Process"
        PuyaPyLSP["PuyaPy Language Server (puyapy.lsp)"]

        subgraph "PuyaPy Frontend"
            PyParser["Python Parser"]
            AWSBuilder["AWST Builder (transform_ast)"]
            FrontendLogCtx["Frontend Logging Context"]
        end

        subgraph "Puya Core Compiler"
            AWSTProcF["AWST Processor"]
            TealCompiler["TEAL Compiler (awst_to_teal)"]
            CompilerLogCtx["Compiler Logging Context"]
        end
    end

    Developer -->|keystroke| VSCodeExt
    VSCodeExt -->|stdio/tcp| PuyaPyLSP

    PuyaPyLSP -->|document changes| PyParser
    PyParser -->|Python AST| AWSBuilder
    AWSBuilder -->|AWST nodes| AWSTProcF
    AWSTProcF -->|processed AWST| TealCompiler

    FrontendLogCtx -.->|diagnostics| PuyaPyLSP
    PyParser -->|parsing results| FrontendLogCtx
    AWSBuilder -->|building results| FrontendLogCtx

    CompilerLogCtx -.->|diagnostics| PuyaPyLSP
    AWSTProcF -->|validation results| CompilerLogCtx
    TealCompiler -->|compilation results| CompilerLogCtx

    PuyaPyLSP -->|diagnostics| VSCodeExt
    VSCodeExt -->|diagnostics| Developer

    class Developer,VSCodeExt vscode
    class PuyaPyLSP pyProcess
    class PyParser,AWSBuilder,FrontendLogCtx frontend
    class AWSTProcF,TealCompiler,CompilerLogCtx coreComp

Algorand TypeScript Language Server

The TypeScript implementation runs the Puya service as a separate process and communicates with it via JSON-RPC over stdin/stdout.

flowchart TB
    subgraph "VSCode IDE"
        Developer["Developer"]
        VSCodeExt["VSCode Extension"]
    end

    subgraph "NodeJS Process"
        PuyaTsLSP["PuyaTS Language Server"]
        PuyaServiceClient["Puya Service Client"]

        subgraph "PuyaTs Frontend"
            TsParser["TypeScript Parser"]
            TsAWSTBuilder["AWST Builder (buildAwst)"]
            FrontendLogCtx["Frontend Logging Context"]
        end
    end

    subgraph "Python Process (subprocess)"
        PuyaService["Puya Service (puya serve)"]

        subgraph "Puya Core Compiler"
            AWST["AWST Processor"]
            TealCompiler["TEAL Compiler (awst_to_teal)"]
            CompilerLogCtx["Compiler Logging Context"]
        end
    end

    Developer -->|keystroke| VSCodeExt
    VSCodeExt -->|stdio/tcp| PuyaTsLSP

    PuyaTsLSP -->|document changes| TsParser
    TsParser -->|TypeScript AST| TsAWSTBuilder
    TsAWSTBuilder -->|AWST nodes| PuyaServiceClient

    FrontendLogCtx -.->|diagnostics| PuyaTsLSP
    TsParser -->|parsing results| FrontendLogCtx
    TsAWSTBuilder -->|building results| FrontendLogCtx

    PuyaServiceClient -->|downloads puya binary, starts & manages| PuyaService

    PuyaServiceClient -->|JSON-RPC: serialized AWST| PuyaService
    PuyaService -->|deserialized AWST| AWST
    AWST -->|processed AWST| TealCompiler
    TealCompiler -->|compilation results| CompilerLogCtx
    AWST -->|validation results| CompilerLogCtx

    CompilerLogCtx -.->|diagnostics| PuyaService
    PuyaService -->|JSON-RPC: diagnostics| PuyaServiceClient
    PuyaServiceClient -->|diagnostics| PuyaTsLSP
    PuyaTsLSP -->|diagnostics| VSCodeExt
    VSCodeExt -->|diagnostics| Developer

    class Developer,VSCodeExt vscode
    class PuyaTsLSP,PuyaServiceClient,FrontendLogCtx nodeProc
    class TsParser,TsAWSTBuilder frontend
    class PuyaService pyProc
    class AWST,TealCompiler,CompilerLogCtx coreComp