# yonyuk/pylgen architecture

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

- Interactive diagram: https://gitdiagram.com/yonyuk/pylgen
- Repository: https://github.com/yonyuk/pylgen

## Overview

PyLGEN is a Python-native compiler and interpreter framework, with a pure-Python development interface and Cython-backed implementations. Its principal workflow takes source text through tokenization, grammar-based parsing and AST construction, then semantic analysis and evaluation, producing a result or errors. Separate capabilities include regex-to-automaton tools and interactive visualizations. The README documents the main pipeline; source excerpts additionally show visualization code using parser-building logic. Other internal connections are omitted where the sampled code does not establish them.

Main entry points: [`pylgen/lexer`](https://github.com/yonyuk/pylgen/tree/master/pylgen/lexer) (Lexer), [`pylgen/parser/parser_builder.pyx`](https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser_builder.pyx) (Parser Builder), [`pylgen/parser/parser.pyx`](https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser.pyx) (Parser Runtime), [`pylgen/common/types.pyx`](https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx) (AST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Processing"]
  node_lexer["Lexer"]
  node_grammar["Grammar"]
  node_parsergen["Parser Builder<br/>[parser_builder.pyx]"]
  node_parser["Parser Runtime<br/>[parser.pyx]"]
  node_ast["AST<br/>[types.pyx]"]
  node_result["Result or Errors<br/>[types.pyx]"]
  node_parsermodes["Parser Modes<br/>[parser_type.py]"]
  node_parseractions["Parser Actions"]
end

subgraph group_foundations["Core Foundations"]
  node_regex["Regex Engine<br/>[engine.pyx]"]
  node_automaton["Finite Automata<br/>[automaton.pyx]"]
  node_coretypes["Core Types<br/>[types.pyx]"]
  node_tokenenums["Token and Error Enums<br/>[enums.py]"]
end

subgraph group_analysis["Analysis"]
  node_semantic["Semantic Analysis<br/>[visitor.pyx]"]
  node_context["Context Management<br/>[context.pyx]"]
  node_evaluation["Evaluation"]
end

subgraph group_visual["Visualization"]
  node_visuals["Interactive Visualizations<br/>[__init__.py]"]
  node_tables["Parser Tables<br/>[table.py]"]
end

node_developer(("Language Author"))
node_source["Source Text"]

node_developer -->|"defines tokens"| node_lexer
node_developer -->|"defines grammar"| node_grammar
node_source -->|"tokenizes"| node_lexer
node_lexer -->|"supplies tokens"| node_parser
node_grammar -->|"generates parser"| node_parsergen
node_parsergen -->|"builds parser"| node_parser
node_parser -->|"constructs AST"| node_ast
node_ast -->|"analyzes"| node_semantic
node_semantic -.->|"uses context"| node_context
node_semantic -->|"evaluates"| node_evaluation
node_evaluation -->|"produces result"| node_result
node_regex -->|"converts to"| node_automaton
node_lexer -->|"uses regex"| node_regex
node_visuals -->|"visualizes"| node_ast
node_visuals -->|"visualizes"| node_automaton
node_visuals -->|"renders tables"| node_tables
node_tables -->|"calls builder"| node_parsergen
node_parser -.->|"dispatches actions"| node_parseractions
node_parsergen -.->|"selects mode"| node_parsermodes
node_lexer -.->|"uses token types"| node_tokenenums
node_ast -.->|"uses core types"| node_coretypes

click node_lexer "https://github.com/yonyuk/pylgen/tree/master/pylgen/lexer"
click node_grammar "https://github.com/yonyuk/pylgen/tree/master/pylgen/grammar"
click node_parsergen "https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser_builder.pyx"
click node_parser "https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser.pyx"
click node_ast "https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx"
click node_semantic "https://github.com/yonyuk/pylgen/blob/master/pylgen/analysis/visitor.pyx"
click node_context "https://github.com/yonyuk/pylgen/blob/master/pylgen/analysis/context.pyx"
click node_evaluation "https://github.com/yonyuk/pylgen/tree/master/pylgen/analysis"
click node_result "https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx"
click node_regex "https://github.com/yonyuk/pylgen/blob/master/pylgen/regex/engine.pyx"
click node_automaton "https://github.com/yonyuk/pylgen/blob/master/pylgen/automaton/automaton.pyx"
click node_coretypes "https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx"
click node_tokenenums "https://github.com/yonyuk/pylgen/blob/master/pylgen/common/enums.py"
click node_parsermodes "https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser_type.py"
click node_parseractions "https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/bottom_up_parser_actions.py"
click node_visuals "https://github.com/yonyuk/pylgen/blob/master/pylgen/visual/__init__.py"
click node_tables "https://github.com/yonyuk/pylgen/blob/master/pylgen/visual/table.py"

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_lexer,node_grammar,node_parsergen,node_parser,node_ast,node_result,node_parsermodes,node_parseractions toneBlue
class node_regex,node_automaton,node_coretypes,node_tokenenums toneAmber
class node_semantic,node_context,node_evaluation toneMint
class node_visuals,node_tables toneRose
class node_developer,node_source toneIndigo
```

## Components

### Language Processing

- [Lexer](https://github.com/yonyuk/pylgen/tree/master/pylgen/lexer): `pylgen/lexer`
- [Grammar](https://github.com/yonyuk/pylgen/tree/master/pylgen/grammar): `pylgen/grammar`
- [Parser Builder](https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser_builder.pyx): `pylgen/parser/parser_builder.pyx`
- [Parser Runtime](https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser.pyx): `pylgen/parser/parser.pyx`
- [AST](https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx): `pylgen/common/types.pyx`
- [Result or Errors](https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx): `pylgen/common/types.pyx`
- [Parser Modes](https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/parser_type.py): `pylgen/parser/parser_type.py`
- [Parser Actions](https://github.com/yonyuk/pylgen/blob/master/pylgen/parser/bottom_up_parser_actions.py): `pylgen/parser/bottom_up_parser_actions.py`

### Core Foundations

- [Regex Engine](https://github.com/yonyuk/pylgen/blob/master/pylgen/regex/engine.pyx): `pylgen/regex/engine.pyx`
- [Finite Automata](https://github.com/yonyuk/pylgen/blob/master/pylgen/automaton/automaton.pyx): `pylgen/automaton/automaton.pyx`
- [Core Types](https://github.com/yonyuk/pylgen/blob/master/pylgen/common/types.pyx): `pylgen/common/types.pyx`
- [Token and Error Enums](https://github.com/yonyuk/pylgen/blob/master/pylgen/common/enums.py): `pylgen/common/enums.py`

### Analysis

- [Semantic Analysis](https://github.com/yonyuk/pylgen/blob/master/pylgen/analysis/visitor.pyx): `pylgen/analysis/visitor.pyx`
- [Context Management](https://github.com/yonyuk/pylgen/blob/master/pylgen/analysis/context.pyx): `pylgen/analysis/context.pyx`
- [Evaluation](https://github.com/yonyuk/pylgen/tree/master/pylgen/analysis): `pylgen/analysis`

### Visualization

- [Interactive Visualizations](https://github.com/yonyuk/pylgen/blob/master/pylgen/visual/__init__.py): `pylgen/visual/__init__.py`
- [Parser Tables](https://github.com/yonyuk/pylgen/blob/master/pylgen/visual/table.py): `pylgen/visual/table.py`

### Other components

- **Language Author**
- **Source Text**

## Connections

- Language Author → Lexer: defines tokens (evidence: `readme.md`)
- Language Author → Grammar: defines grammar (evidence: `readme.md`)
- Source Text → Lexer: tokenizes (evidence: `readme.md`)
- Lexer → Parser Runtime: supplies tokens (evidence: `readme.md`)
- Grammar → Parser Builder: generates parser (evidence: `readme.md`)
- Parser Builder → Parser Runtime: builds parser (evidence: `readme.md`)
- Parser Runtime → AST: constructs AST (evidence: `readme.md`)
- AST → Semantic Analysis: analyzes (evidence: `readme.md`)
- Semantic Analysis → Context Management: uses context
- Semantic Analysis → Evaluation: evaluates (evidence: `readme.md`)
- Evaluation → Result or Errors: produces result (evidence: `readme.md`)
- Regex Engine → Finite Automata: converts to (evidence: `readme.md`)
- Lexer → Regex Engine: uses regex (evidence: `readme.md`)
- Interactive Visualizations → AST: visualizes (evidence: `readme.md`)
- Interactive Visualizations → Finite Automata: visualizes (evidence: `readme.md`)
- Interactive Visualizations → Parser Tables: renders tables (evidence: `pylgen/visual/__init__.py`)
- Parser Tables → Parser Builder: calls builder (evidence: `pylgen/visual/table.py`)
- Parser Runtime → Parser Actions: dispatches actions
- Parser Builder → Parser Modes: selects mode
- Lexer → Token and Error Enums: uses token types
- AST → Core Types: uses core types