# plc-lang/rusty architecture

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

- Interactive diagram: https://gitdiagram.com/plc-lang/rusty
- Repository: https://github.com/plc-lang/rusty

## Overview

##### Main components
- Compiler Frontend: Represent the tokenization and parsing phases. Components include the Lexer (src/lexer, tests), Parser (src/parser and its tests), and the AST construction in the various “plc_ast” modules.
- Semantic Analysis & Indexing: Show the role of symbol resolution and type checking. This includes the indexing crates (compiler/plc_index, src/index) and resolver (src/resolver, including const evaluator and generics) which work together to validate the structured text and build a semantic model.
- Lowering and Validation: Indicate the “lowering” phase (compiler/plc_lowering and src/lowering) that converts the high-level AST into an intermediate representation with proper type conversions and checks. In parallel, the “validation” parts (src/validation) ensure that language and domain‐specific rules are enforced.
- Code Generation: Include the CodeGen modules (src/codegen and its generators) that interact with LLVM (evident via files like src/codegen/llvm_index.rs and src/codegen/llvm_typesystem.rs) to create native IR/code.
- Compiler Driver / CLI: The overall entry-point is managed by components such as “compiler/plc_driver” where the command line interface (cli.rs) dispatches to the various compiler pipelines.
- Auxiliary Components: There are integration components like the “xtask” directory which handles building, reporting, and utility tasks, plus the “libs/stdlib” which provides the standard library functions for Structured Text programs.

##### Relationships and Data Flows
- Flow begins at the Compiler Driver/CLI: Input Structured Text source files (from examples or user inputs) are fed into the Lexer.
- The Lexer tokenizes the input, passing tokens to the Parser.
- The Parser constructs an AST that is enriched by derive macros (compiler/plc_derive) and later annotated by the Diagnostics (compiler/plc_diagnostics).
- The AST is processed by the Indexer to build symbol tables and resolve dependencies.
- Next, the Lowering phase converts the high-level AST into a lower-level intermediate representation while validating types, performing optimizations, and flagging errors.
- The Code Generation phase then takes over, using LLVM-based generators to produce the native code.
- Finally, the Linker (src/linker.rs, scripts/linker) ties the output together into an executable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend"
        CLI["CLI/Driver"]:::frontend
        LEX["Lexer"]:::frontend
        PARSER["Parser & AST"]:::frontend
        DIAG["Diagnostics"]:::diag
    end

    %% Semantic Analysis Subgraph
    subgraph "Semantic Analysis"
        INDEX["Indexing/Resolver"]:::analysis
    end

    %% Lowering & Validation Subgraph
    subgraph "Lowering & Validation"
        LOWER["Lowering & Validation"]:::lowering
    end

    %% Code Generation Subgraph
    subgraph "Code Generation"
        CODEGEN["Code Generation"]:::codegen
        LINKER["Linker/Output"]:::codegen
    end

    %% Auxiliary Subgraph
    subgraph "Auxiliary"
        STD["Standard Library"]:::auxiliary
        XTASK["Build/Task Utilities"]:::auxiliary
    end

    %% External Dependency
    LLVM["LLVM"]:::external

    %% Flow Connections
    CLI -->|"feeds"| LEX
    LEX -->|"tokenizes to"| PARSER
    PARSER -- "annotates" --> DIAG
    PARSER -->|"builds AST for"| INDEX
    INDEX -->|"prepares semantic model for"| LOWER
    LOWER -->|"transforms IR for"| CODEGEN
    CODEGEN -->|"generates native code to"| LINKER
    CODEGEN -->|"uses"| LLVM

    %% Auxiliary Connections
    XTASK -.->|"supports build tasks for"| CLI
    STD -.->|"provides built-in functions to"| PARSER

    %% Click Events for Compiler Frontend
    click LEX "https://github.com/plc-lang/rusty/tree/master/src/lexer"
    click PARSER "https://github.com/plc-lang/rusty/tree/master/src/parser"
    click PARSER "https://github.com/plc-lang/rusty/tree/master/compiler/plc_ast"

    %% Click Events for Semantic Analysis & Indexing
    click INDEX "https://github.com/plc-lang/rusty/tree/master/compiler/plc_index"
    click INDEX "https://github.com/plc-lang/rusty/tree/master/src/index"
    click INDEX "https://github.com/plc-lang/rusty/tree/master/src/resolver"

    %% Click Events for Lowering and Validation
    click LOWER "https://github.com/plc-lang/rusty/tree/master/compiler/plc_lowering"
    click LOWER "https://github.com/plc-lang/rusty/tree/master/src/lowering"
    click LOWER "https://github.com/plc-lang/rusty/tree/master/src/validation"

    %% Click Events for Code Generation
    click CODEGEN "https://github.com/plc-lang/rusty/tree/master/src/codegen"

    %% Click Event for Compiler Driver / CLI
    click CLI "https://github.com/plc-lang/rusty/tree/master/compiler/plc_driver"

    %% Click Events for Auxiliary Components
    click STD "https://github.com/plc-lang/rusty/tree/master/libs/stdlib"
    click XTASK "https://github.com/plc-lang/rusty/tree/master/xtask"

    %% Styles
    classDef frontend fill:#aee1ff,stroke:#333,stroke-width:1px;
    classDef analysis fill:#caffbf,stroke:#333,stroke-width:1px;
    classDef lowering fill:#ffdfba,stroke:#333,stroke-width:1px;
    classDef codegen fill:#ffb3ba,stroke:#333,stroke-width:1px;
    classDef auxiliary fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef diag fill:#ffd1dc,stroke:#333,stroke-width:1px;
    classDef external fill:#d0e6a5,stroke:#333,stroke-width:1px;
```
