# terostechnology/vscode-teroshdl architecture

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

- Interactive diagram: https://gitdiagram.com/terostechnology/vscode-teroshdl
- Repository: https://github.com/terostechnology/vscode-teroshdl

## Overview

##### VSCode Plugin Frontend
- Extension user interface that interacts with the user.
- Integration with webviews (e.g., dependencies viewer, documenter, schematic viewer, state machine viewer).
- That the plugin sends commands to and receives data from the backend modules.

##### Core Backend Modules (located under the “src” directory)
- Colibri Library: This module covers many sub-components such as commands, configuration management, documenters, formatters, linters, parsers, reporters, project manager, and others.
- TerosHDL Features: Under “src/teroshdl”, features like language provider, tree views, completions, configuration checkers, and integration with external tools (like ctags and LSP support) are implemented.
- Each of these can be shown as separate layered components that handle specific functionalities (e.g., formatting, linting, dependency/project management, parsing, and tool integration).

##### Auto Package and Code Generation
- The “auto_package” directory contains YAML and template files used for dynamic generation of configurations or project files.

##### External Tools Integration
- External simulation and synthesis tools (Raptor, Vivado, ModelSim, GHDL, Verilator, Icarus, etc.) that the toolbox supports.
- As external services or integrations where the backend modules (e.g., project manager and tool handlers) call these command-line tools.

##### Language Servers and Server-Side Tools
- In the “server” directory, the project includes a VHDL language server (“vhdl_ls”) provided in different builds (Windows, Linux, etc.). Indicate this as a dedicated service that supports “go to definition”, hover, and other language-related features.
- Connection from the VSCode plugin and/or the colibri backend to this language server to provide language features.

##### Configuration and Resource Management
- The “configs” directory contains system configuration files for File Types (Verilog, VHDL, SystemVerilog, TCL, etc.).
- That these components configure the behavior of different modules and are loaded at runtime by the core backend or the plugin.

##### Testing and Documentation
- Though separate, the “tests” directory (and “tests_impr”) shows that thorough testing is done for functionalities like parsing, formatting, project management, document generation, and tool integration.

Architectural Patterns and Design Principles:
- Modular Design: Each subdirectory and module (colibri, terosHDL features, server tools, auto_package) represents a loosely coupled component that communicates via well-defined interfaces.
- Separation of Concerns: The frontend VSCode extension interacts with the various backends (formatters, linters, documenters, language servers, auto generation) rather than implementing complex logic within the UI layer.
- Extensibility: The system uses configuration files and templates (YAML, .nj templates) that permit new tools or formats to be easily added.

- Use clearly labeled nodes for each major module (Frontend, Colibri core, TerosHDL features, Auto Package, External Tools, Server/Language Server, Configs/Resources).
– Between the VSCode plugin and the backend services (for example, how user actions trigger commands that go to the formatter, linter, and documenter).
– From backend modules to external HDL tools and simulators.
- Use annotations or callouts to indicate specific technologies:
– Note that the project uses Node.js (npm, jest tests), has integrated GitHub actions for CI/CD, and contains configurations and assets typical of VSCode extensions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    A("VSCode Plugin Frontend"):::frontend
    A2("Webviews"):::frontend

    %% Backend Modules
    B("Colibri Core"):::backend
    C("TerosHDL Features"):::backend
    D("Auto Package & Code Generation"):::backend
    G("Language Server"):::backend

    %% External Tools Integration
    E("Tool Handlers"):::external
    F("Supporting Binaries"):::external

    %% Configuration and Resources
    H("Configs"):::config
    I("Assets/Resources"):::config

    %% Quality Assurance
    J("Tests"):::qa
    K("CI/CD Workflows"):::qa

    %% Connections between Frontend and Backend
    A -->|"sendsCommands"| B
    A -->|"sendsCommands"| C
    A -->|"requestsLangFeatures"| G
    A2 -->|"rendersInUI"| A

    %% Backend intercommunications
    B -->|"invokes"| E
    C -->|"invokes"| E
    B -->|"calls"| G
    C -->|"calls"| G

    %% Use of Auto Package
    B -->|"utilizes"| D
    C -->|"utilizes"| D
    D -->|"suppliesTemplates"| B
    D -->|"suppliesTemplates"| C

    %% Configuration and Resources provide support
    H -->|"configures"| B
    H -->|"configures"| C
    I -->|"suppliesAssets"| A
    I -->|"suppliesAssets"| B
    I -->|"suppliesAssets"| C

    %% External Tools Integration internal connection
    E -->|"utilizes"| F

    %% Quality Assurance connections
    A ---|"testedBy"| J
    B ---|"testedBy"| J
    C ---|"testedBy"| J
    J -->|"triggers"| K

    %% Click Events
    click A "https://github.com/terostechnology/vscode-teroshdl/blob/dev/src/teroshdl/extension.ts"
    click A2 "https://github.com/terostechnology/vscode-teroshdl/tree/dev/resources/webviews"
    click B "https://github.com/terostechnology/vscode-teroshdl/tree/dev/src/colibri"
    click C "https://github.com/terostechnology/vscode-teroshdl/tree/dev/src/teroshdl/features"
    click D "https://github.com/terostechnology/vscode-teroshdl/tree/dev/auto_package"
    click E "https://github.com/terostechnology/vscode-teroshdl/tree/dev/src/colibri/project_manager/tool"
    click F "https://github.com/terostechnology/vscode-teroshdl/tree/dev/resources/bin/ctags"
    click G "https://github.com/terostechnology/vscode-teroshdl/tree/dev/server/vhdl_ls"
    click H "https://github.com/terostechnology/vscode-teroshdl/tree/dev/configs"
    click I "https://github.com/terostechnology/vscode-teroshdl/tree/dev/resources"
    click J "https://github.com/terostechnology/vscode-teroshdl/tree/dev/tests"
    click K "https://github.com/terostechnology/vscode-teroshdl/tree/dev/.github/workflows"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef backend fill:#d5e8d4,stroke:#000,stroke-width:2px;
    classDef external fill:#f8cecc,stroke:#000,stroke-width:2px;
    classDef config fill:#fff2cc,stroke:#000,stroke-width:2px;
    classDef qa fill:#d9d2e9,stroke:#000,stroke-width:2px;
```
