# eldarsalmanow/gslanguage architecture

> Architecture diagram of the GitHub repository eldarsalmanow/gslanguage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eldarsalmanow/gslanguage
- Repository: https://github.com/eldarsalmanow/gslanguage

## Overview

1. **What this repo is**
   GSLanguage is a C++20 implementation of a compiled programming language. The repository is organized as a compiler toolchain rather than an application: it takes source text through analysis stages and ends with code generation.

2. **Top-level architecture**
   The project is split into clear compiler subsystems under `include/` and `src/`: `IO`, `Lexer`, `Parser`, `AST`, `Semantic`, `Optimizer`, `CodeGenerator`, `Driver`, and `Debug`. The mirrored `include/...` and `src/...` layout indicates a library-style core with headers exposing the compiler API and source files implementing each stage.

3. **Input and source management**
   The `IO` layer is the entry point for files/streams/messages. Classes like `GS_Source`, `GS_Reader`, and `GS_Stream` likely normalize input from files or buffers, while `GS_Message` provides structured diagnostics. This layer forms the boundary between raw text and compiler processing.

4. **Lexing and tokenization**
   The `Lexer` subsystem converts source text into tokens. It includes cursor/token abstractions and token type definitions in `GS_TokenTypes.def`, suggesting a centralized token catalog used by both lexer and parser. This stage produces the stream consumed by parsing.

5. **Parsing and grammar**
   The `Parser` turns tokens into the language’s AST. The presence of `GRAMMAR.md` and `GS_Parser` indicates the grammar is documented separately from implementation. Parsing is the syntactic boundary: it translates language structure into tree nodes without doing type or semantic resolution.

6. **AST as the central internal model**
   The `AST` directory is the shared core model used by downstream stages. It contains base node types plus concrete declarations, statements, and expressions such as functions, imports, modules, literals, binary/unary operations, control flow, calls, arrays, ranges, and indexing. `GS_ASTBuilder` and `GS_ASTContext` suggest AST construction is context-aware and likely owns node creation and source association.

7. **Semantic analysis and symbol/type state**
   The `Semantic` subsystem resolves meaning after parsing. It includes `GS_TableOfSymbols`, `GS_Type`, and semantic passes such as `GS_SymbolsPlaceholderPass` and `GS_TypeInferencePass`. This stage is where identifiers, scopes, and inferred types are established, forming the semantic boundary before optimization or emission.

8. **Optimization**
   The `Optimizer` currently appears small and pass-based, with `GS_ConstantFoldingPass` as the notable transformation. It likely operates on the analyzed AST or an intermediate representation derived from it, performing local compile-time simplifications before code generation.

9. **Code generation and backend abstraction**
   `CodeGenerator` provides an abstraction over emission targets via `GS_Backend` and `GS_CodeGenerator`, with an LLVM-specific implementation in `CodeGenerator/LLVM`. `GS_LLVMVisitor` and `GS_LLVMBackend` show that LLVM is a material external dependency and the current backend target. The architecture is backend-oriented, so the compiler can be extended with additional targets behind the same interface.

10. **Driver, sessions, and orchestration**
   The `Driver` layer coordinates the compilation pipeline. Classes like `GS_Compiler`, `GS_SessionManager`, `GS_Session`, `GS_GlobalContext`, `GS_Arguments`, and `GS_QueryManager` suggest a higher-level API for running compilations, managing state across runs, and handling queries or commands. This is the control plane that ties IO, parsing, semantics, optimization, and codegen together.

11. **Debugging and observability**
   `Debug` contains AST and symbol-table dumpers. These are important architectural tools because they expose internal compiler state at stage boundaries, making it easier to inspect how source text becomes AST, symbols, and types.

12. **Examples, tests, and build system**
   The repository uses CMake throughout, with an `external/conanfile.txt` indicating dependency management through Conan. `examples/` includes sample `.gs`, `.c`, `.rs`, and assembly files, likely used to exercise compilation or integration points. `tests/` currently focuses on `IO`, `Lexer`, and `Parser`, which matches the earliest pipeline stages where correctness is most foundational.

Main entry points: [`include/Driver`](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Driver) (Driver), [`include/Parser`](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Parser) (Parser), [`include/Semantic`](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Semantic) (Semantic), [`include/IO`](https://github.com/eldarsalmanow/gslanguage/tree/master/include/IO) (IO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Compiler core"]
  node_io[("IO<br/>source + diagnostics")]
  node_lexer["Lexer<br/>tokenizer"]
  node_parser["Parser<br/>syntax analysis"]
  node_ast{{"AST<br/>core model"}}
  node_semantic["Semantic<br/>analysis passes"]
  node_optimizer["Optimizer<br/>transform passes"]
  node_codegen["CodeGen<br/>backend layer"]
  node_llvm["LLVM<br/>target backend"]
end

subgraph group_api["Public API"]
  node_io_api["IO API<br/>headers<br/>[IO.h]"]
  node_lexer_api["Lexer API<br/>headers<br/>[Lexer.h]"]
  node_parser_api["Parser API<br/>headers<br/>[Parser.h]"]
  node_ast_api["AST API<br/>headers<br/>[AST.h]"]
  node_semantic_api["Semantic API<br/>headers<br/>[Semantic.h]"]
  node_codegen_api["CodeGen API<br/>headers<br/>[CodeGenerator.h]"]
end

subgraph group_support["Support"]
  node_driver["Driver<br/>orchestration"]
  node_debug["Debug<br/>dumps"]
  node_examples["Examples<br/>usage samples"]
  node_tests["Tests<br/>validation"]
end

node_io -->|"source text"| node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"trees"| node_ast
node_ast -->|"analysis input"| node_semantic
node_semantic -->|"typed tree"| node_optimizer
node_optimizer -->|"lowered tree"| node_codegen
node_codegen -->|"backend impl"| node_llvm
node_driver -->|"orchestrates"| node_io
node_driver -->|"runs pipeline"| node_parser
node_driver -->|"runs pipeline"| node_semantic
node_driver -->|"runs pipeline"| node_optimizer
node_driver -->|"runs pipeline"| node_codegen
node_debug -->|"dumps"| node_ast
node_debug -->|"dumps"| node_semantic
node_examples -->|"exercise"| node_driver
node_tests -->|"covers"| node_io
node_tests -->|"covers"| node_lexer
node_tests -->|"covers"| node_parser
node_io_api -->|"exposes"| node_io
node_lexer_api -->|"exposes"| node_lexer
node_parser_api -->|"exposes"| node_parser
node_ast_api -->|"exposes"| node_ast
node_semantic_api -->|"exposes"| node_semantic
node_codegen_api -->|"exposes"| node_codegen

click node_io "https://github.com/eldarsalmanow/gslanguage/tree/master/include/IO"
click node_lexer "https://github.com/eldarsalmanow/gslanguage/tree/master/include/Lexer"
click node_parser "https://github.com/eldarsalmanow/gslanguage/tree/master/include/Parser"
click node_ast "https://github.com/eldarsalmanow/gslanguage/tree/master/include/AST"
click node_semantic "https://github.com/eldarsalmanow/gslanguage/tree/master/include/Semantic"
click node_optimizer "https://github.com/eldarsalmanow/gslanguage/tree/master/include/Optimizer"
click node_codegen "https://github.com/eldarsalmanow/gslanguage/tree/master/include/CodeGenerator"
click node_llvm "https://github.com/eldarsalmanow/gslanguage/tree/master/include/CodeGenerator/LLVM"
click node_driver "https://github.com/eldarsalmanow/gslanguage/tree/master/include/Driver"
click node_debug "https://github.com/eldarsalmanow/gslanguage/tree/master/include/Debug"
click node_examples "https://github.com/eldarsalmanow/gslanguage/tree/master/examples"
click node_tests "https://github.com/eldarsalmanow/gslanguage/tree/master/tests"
click node_io_api "https://github.com/eldarsalmanow/gslanguage/blob/master/include/IO/IO.h"
click node_lexer_api "https://github.com/eldarsalmanow/gslanguage/blob/master/include/Lexer/Lexer.h"
click node_parser_api "https://github.com/eldarsalmanow/gslanguage/blob/master/include/Parser/Parser.h"
click node_ast_api "https://github.com/eldarsalmanow/gslanguage/blob/master/include/AST/AST.h"
click node_semantic_api "https://github.com/eldarsalmanow/gslanguage/blob/master/include/Semantic/Semantic.h"
click node_codegen_api "https://github.com/eldarsalmanow/gslanguage/blob/master/include/CodeGenerator/CodeGenerator.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_io,node_lexer,node_parser,node_ast,node_semantic,node_optimizer,node_codegen,node_llvm toneBlue
class node_io_api,node_lexer_api,node_parser_api,node_ast_api,node_semantic_api,node_codegen_api toneAmber
class node_driver,node_debug,node_examples,node_tests toneMint
```

## Components

### Compiler core

Main compilation pipeline from source input to generated code.

- [IO](https://github.com/eldarsalmanow/gslanguage/tree/master/include/IO): source + diagnostics · Reads sources, streams, and compiler messages. · `include/IO`
- [Lexer](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Lexer): tokenizer · Converts source text into tokens. · `include/Lexer`
- [Parser](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Parser): syntax analysis · Builds syntax trees from the token stream. · `include/Parser`
- [AST](https://github.com/eldarsalmanow/gslanguage/tree/master/include/AST): core model · Shared tree representation used by later compiler stages. · `include/AST`
- [Semantic](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Semantic): analysis passes · Resolves symbols, scopes, and types. · `include/Semantic`
- [Optimizer](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Optimizer): transform passes · Performs compile-time simplifications on the analyzed tree. · `include/Optimizer`
- [CodeGen](https://github.com/eldarsalmanow/gslanguage/tree/master/include/CodeGenerator): backend layer · Emits target code through a backend abstraction. · `include/CodeGenerator`
- [LLVM](https://github.com/eldarsalmanow/gslanguage/tree/master/include/CodeGenerator/LLVM): target backend · LLVM-backed code generation implementation. · `include/CodeGenerator/LLVM`

### Public API

Headers exposing the compiler subsystems.

- [IO API](https://github.com/eldarsalmanow/gslanguage/blob/master/include/IO/IO.h): headers · Public IO interfaces and message types. · `include/IO/IO.h`
- [Lexer API](https://github.com/eldarsalmanow/gslanguage/blob/master/include/Lexer/Lexer.h): headers · Public lexer interfaces and token definitions. · `include/Lexer/Lexer.h`
- [Parser API](https://github.com/eldarsalmanow/gslanguage/blob/master/include/Parser/Parser.h): headers · Public parser interface and grammar documentation. · `include/Parser/Parser.h`
- [AST API](https://github.com/eldarsalmanow/gslanguage/blob/master/include/AST/AST.h): headers · Public AST node, visitor, and builder interfaces. · `include/AST/AST.h`
- [Semantic API](https://github.com/eldarsalmanow/gslanguage/blob/master/include/Semantic/Semantic.h): headers · Public semantic analysis types and passes. · `include/Semantic/Semantic.h`
- [CodeGen API](https://github.com/eldarsalmanow/gslanguage/blob/master/include/CodeGenerator/CodeGenerator.h): headers · Public backend and code generator interfaces. · `include/CodeGenerator/CodeGenerator.h`

### Support

Orchestration, diagnostics, and examples around the core compiler.

- [Driver](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Driver): orchestration · Coordinates sessions, arguments, queries, and compilation runs. · `include/Driver`
- [Debug](https://github.com/eldarsalmanow/gslanguage/tree/master/include/Debug): dumps · AST and symbol-table dumpers for observing compiler state. · `include/Debug`
- [Examples](https://github.com/eldarsalmanow/gslanguage/tree/master/examples): usage samples · Sample inputs and integration examples for the compiler. · `examples`
- [Tests](https://github.com/eldarsalmanow/gslanguage/tree/master/tests): validation · Unit tests for IO, lexer, and parser behavior. · `tests`

## Connections

- IO → Lexer: source text · Normalized source input flows into lexical analysis.
- Lexer → Parser: tokens · Token stream feeds parsing.
- Parser → AST: trees · Parsing produces the AST as the central internal model.
- AST → Semantic: analysis input · Semantic passes operate on AST nodes.
- Semantic → Optimizer: typed tree · Optimization runs after meaning is established.
- Optimizer → CodeGen: lowered tree · Optimized representation is emitted by code generation.
- CodeGen → LLVM: backend impl · LLVM is the concrete target backend.
- Driver → IO: orchestrates · Driver configures source and diagnostic handling.
- Driver → Parser: runs pipeline · Compiler orchestration invokes parsing and later stages.
- Driver → Semantic: runs pipeline · Driver controls semantic analysis.
- Driver → Optimizer: runs pipeline · Driver controls optimization passes.
- Driver → CodeGen: runs pipeline · Driver triggers backend emission.
- Debug → AST: dumps · AST dumper inspects tree structure.
- Debug → Semantic: dumps · Symbol-table dumper inspects semantic state.
- Examples → Driver: exercise · Sample programs demonstrate compiler usage.
- Tests → IO: covers · IO tests validate the input layer.
- Tests → Lexer: covers · Lexer tests validate tokenization.
- Tests → Parser: covers · Parser tests validate grammar handling.
- IO API → IO: exposes · Public IO headers define the IO layer API.
- Lexer API → Lexer: exposes · Public lexer headers define tokenization APIs.
- Parser API → Parser: exposes · Public parser headers define syntax analysis APIs.
- AST API → AST: exposes · Public AST headers define the shared tree model.
- Semantic API → Semantic: exposes · Public semantic headers define analysis APIs.
- CodeGen API → CodeGen: exposes · Public code generation headers define backend APIs.