# utwente-fmt/vercors architecture

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

- Interactive diagram: https://gitdiagram.com/utwente-fmt/vercors
- Repository: https://github.com/utwente-fmt/vercors

## Overview

##### Overall Structure and Main Components
- Frontend Parsers and Language Adapters:
– Their task is to convert source programs into an intermediate abstract syntax tree (AST).
- Intermediate Representation (IR) and the Core “col” Module:
– The “src/col/vct” directory contains the core AST definitions, node implementations, declaration modules, expression constructs, and type definitions. This layer represents a common IR used throughout the toolset.
- Rewriting and Transformation Passes:
– The project has many rewriting rules and transformation passes (located under “src/rewrite/vct/rewrite” and subdirectories such as “lang”, “cfg”, “rasi”, “veymont”, and “adt”). These are used to gradually simplify, resolve types, disambiguate ambiguities, and generate the final proof obligations.
- Verification Engine and Status Stages:
– The “src/main/vct” folder contains the main entry (the “Main.scala”) as well as several “stages” (e.g., Parsing, Resolution, Transformation, Expected Errors, and Output), which process the IR and ultimately drive the verification process.
- Backend Integration and External Dependencies:
– In addition, a “viper” subproject exists (under “src/viper”) which handles, for instance, translation to the Silver verification language and integration with Viper’s toolchain.
- Utility, Logging, and Platform-Specific Modules:
– Several directories (such as “src/hre” and “src/util”) provide logging, caching, platform abstraction, and helper routines to facilitate reporting, progress indication, and debugging.

##### Relationships and Data Flows
– User supplies a file (e.g., a Java, C, or PVL program) via the command‐line run script (located in “bin”).
- Next comes the Frontend Parser:
– The selected language-specific parser (ANTLR-based) reads the source code and produces an AST.
- Common IR Construction:
– The AST is converted into the “col” model (the VCT core) and enriched with type information, contracts, and annotations.
- Transformation / Rewriting Pipeline:
– Several rewriting passes are performed sequentially – e.g., disambiguation, inlining, type coercion, and handling of specific concurrency constructs.
- Verification Stage:
– After transformation, the verification engine generates proof obligations or translates the IR to intermediate languages (like Boogie or SMT constraints) that external solvers (Z3, Boogie) process.
- Output Layer:
– The tool then produces a verification result with error messages or success notifications.

##### Architectural Patterns and Design Principles
- Layered Architecture:
- Modularity and Extensibility:
– Modules are well separated (for instance “rewrite”, “parsers”, “vct”, “viper”). This encourages new frontends or new transformation passes without disturbing the overall architecture.
- Use of External Tools:
– Components that interface with external solvers are clearly isolated, promoting a clean boundary between the internal analysis and external proof checking.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        A["User Input (Source File)"]:::input
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        B["Frontend Parsers (ANTLR)"]:::frontend
        B1["ANTLR Grammar Files"]:::frontend
        B2["Language-specific Parser Implementations"]:::frontend
    end

    %% IR Layer
    subgraph "IR Layer"
        C["IR and Core AST (col)"]:::ir
    end

    %% Transformation Layer
    subgraph "Transformation Layer"
        D["Rewrite/Transformation Pipeline"]:::transformation
    end

    %% Verification Layer
    subgraph "Verification Layer"
        E["Verification Engine & Status Stages"]:::verification
    end

    %% Backend Integration
    subgraph "Backend Integration"
        F["Backend Integration (Boogie/Z3)"]:::backend
        F1["Viper Integration"]:::backend
    end

    %% Utility Layer
    subgraph "Utility Layer"
        G["Utility, Logging & Platform Modules"]:::utility
    end

    %% Output Layer
    subgraph "Output Layer"
        H["Verification Result"]:::input
    end

    %% Connections
    A -->|"submit"| B
    B -->|"parses to AST"| B1
    B -->|"parses to AST"| B2
    B1 -->|"generates"| C
    B2 -->|"generates"| C
    C -->|"IR transformation"| D
    D -->|"verification process"| E
    E -->|"calls external tools"| F
    E -->|"calls Viper translator"| F1
    E -->|"produces"| H
    G ---|"supports"| E

    %% Click Events
    click B1 "https://github.com/utwente-fmt/vercors/tree/dev//src/parsers/antlr4"
    click B2 "https://github.com/utwente-fmt/vercors/tree/dev//src/parsers/vct/parsers"
    click C "https://github.com/utwente-fmt/vercors/tree/dev//src/col/vct/col/ast"
    click D "https://github.com/utwente-fmt/vercors/tree/dev//src/rewrite/vct/rewrite"
    click E "https://github.com/utwente-fmt/vercors/tree/dev//src/main/vct/main"
    click F "https://github.com/utwente-fmt/vercors/tree/dev//res/universal/deps"
    click F1 "https://github.com/utwente-fmt/vercors/tree/dev//src/viper"
    click G "https://github.com/utwente-fmt/vercors/tree/dev//src/hre"

    %% Styles
    classDef input fill:#ffdddd,stroke:#dd0000,stroke-width:2px
    classDef frontend fill:#ddffdd,stroke:#008800,stroke-width:2px
    classDef ir fill:#ddddff,stroke:#0000dd,stroke-width:2px
    classDef transformation fill:#fff0b3,stroke:#b38f00,stroke-width:2px
    classDef verification fill:#ffd700,stroke:#b8860b,stroke-width:2px
    classDef backend fill:#ffd1dc,stroke:#ff69b4,stroke-width:2px
    classDef utility fill:#e0ffff,stroke:#008b8b,stroke-width:2px
```
