# kolesole/rtgl architecture

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

- Interactive diagram: https://gitdiagram.com/kolesole/rtgl
- Repository: https://github.com/kolesole/rtgl

## Overview

RTGL turns a user-authored relational prediction query into generated SQL and, optionally, an executed result table. The main workflow is query parsing, conversion to a structured representation, schema-aware validation and relationship resolution, then static or timestamp-based SQL generation. The README also documents explicit Common Path Expressions and raw-SQL virtual tables as query capabilities. Architecture details for some unsampled modules are based on the README and repository tree; uncertain internal wiring is omitted.

Main entry points: [`rtgl/validator/validator.py`](https://github.com/kolesole/rtgl/blob/main/rtgl/validator/validator.py) (Validator base), [`rtgl/converter/temporal_converter.py`](https://github.com/kolesole/rtgl/blob/main/rtgl/converter/temporal_converter.py) (Temporal converter), [`rtgl/converter/converter.py`](https://github.com/kolesole/rtgl/blob/main/rtgl/converter/converter.py) (Converter base), [`rtgl/converter/static_converter.py`](https://github.com/kolesole/rtgl/blob/main/rtgl/converter/static_converter.py) (Static converter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Query language"]
  node_query["RTGL query"]
  node_parser["ANTLR parser<br/>[ParserRTGL.py]"]
  node_grammar["RTGL grammar<br/>[ParserRTGL.g4]"]
  node_visitor["Query visitor<br/>[visitor.py]"]
  node_parsed["Parsed values<br/>[parsed_value.py]"]
end

subgraph group_validation["Validation and schema"]
  node_validator["Validator base<br/>[validator.py]"]
  node_staticval["Static validation"]
  node_temporalval["Temporal validation"]
  node_diagnostics["Validation diagnostics<br/>[diagnostics.py]"]
  node_explorer["Database explorer"]
  node_paths["Path builder<br/>[path_builder.py]"]
end

subgraph group_conversion["SQL conversion"]
  node_converter["Converter base<br/>[converter.py]"]
  node_static["Static converter"]
  node_temporal["Temporal converter"]
end

subgraph group_runtime["Execution and data"]
  node_database[("Relational database<br/>[database.py]")]
  node_table["Table metadata<br/>[table.py]"]
  node_duckdb[("DuckDB")]
  node_result["SQL or result table<br/>[table.py]"]
end

node_user(("Query author"))
node_timestamps["Prediction timestamps"]

node_user -->|"writes"| node_query
node_query -->|"parses"| node_parser
node_grammar -->|"defines syntax"| node_parser
node_parser -->|"provides parse tree"| node_visitor
node_visitor -->|"builds values"| node_parsed
node_visitor -->|"returns query model"| node_converter
node_converter -->|"validates"| node_validator
node_validator -->|"uses for static"| node_staticval
node_validator -->|"uses for temporal"| node_temporalval
node_validator -->|"reports issues"| node_diagnostics
node_validator -->|"resolves schema"| node_explorer
node_validator -->|"resolves joins"| node_paths
node_explorer -->|"inspects"| node_database
node_converter -->|"supports static"| node_static
node_converter -->|"supports temporal"| node_temporal
node_static -->|"reads"| node_database
node_temporal -->|"reads"| node_database
node_timestamps -->|"sets evaluation times"| node_temporal
node_temporal -->|"returns result table"| node_result
node_static -->|"returns SQL or table"| node_result
node_temporal -->|"executes SQL"| node_duckdb
node_static -->|"executes SQL"| node_duckdb
node_duckdb -->|"returns query rows"| node_result

click node_parser "https://github.com/kolesole/rtgl/blob/main/rtgl/parser/gen/ParserRTGL.py"
click node_grammar "https://github.com/kolesole/rtgl/blob/main/rtgl/parser/ParserRTGL.g4"
click node_visitor "https://github.com/kolesole/rtgl/blob/main/rtgl/visitor/visitor.py"
click node_parsed "https://github.com/kolesole/rtgl/blob/main/rtgl/visitor/parsed_value.py"
click node_converter "https://github.com/kolesole/rtgl/blob/main/rtgl/converter/converter.py"
click node_static "https://github.com/kolesole/rtgl/blob/main/rtgl/converter/static_converter.py"
click node_temporal "https://github.com/kolesole/rtgl/blob/main/rtgl/converter/temporal_converter.py"
click node_validator "https://github.com/kolesole/rtgl/blob/main/rtgl/validator/validator.py"
click node_staticval "https://github.com/kolesole/rtgl/blob/main/rtgl/validator/static_validator.py"
click node_temporalval "https://github.com/kolesole/rtgl/blob/main/rtgl/validator/temporal_validator.py"
click node_diagnostics "https://github.com/kolesole/rtgl/blob/main/rtgl/validator/diagnostics.py"
click node_explorer "https://github.com/kolesole/rtgl/blob/main/rtgl/base/database_explorer.py"
click node_paths "https://github.com/kolesole/rtgl/blob/main/rtgl/base/path_builder.py"
click node_database "https://github.com/kolesole/rtgl/blob/main/rtgl/base/database.py"
click node_table "https://github.com/kolesole/rtgl/blob/main/rtgl/base/table.py"
click node_result "https://github.com/kolesole/rtgl/blob/main/rtgl/base/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_query,node_parser,node_grammar,node_visitor,node_parsed toneBlue
class node_validator,node_staticval,node_temporalval,node_diagnostics,node_explorer,node_paths toneAmber
class node_converter,node_static,node_temporal toneMint
class node_database,node_table,node_duckdb,node_result toneRose
class node_user,node_timestamps toneIndigo
```

## Components

### Query language

- **RTGL query**
- [ANTLR parser](https://github.com/kolesole/rtgl/blob/main/rtgl/parser/gen/ParserRTGL.py): `rtgl/parser/gen/ParserRTGL.py`
- [RTGL grammar](https://github.com/kolesole/rtgl/blob/main/rtgl/parser/ParserRTGL.g4): `rtgl/parser/ParserRTGL.g4`
- [Query visitor](https://github.com/kolesole/rtgl/blob/main/rtgl/visitor/visitor.py): `rtgl/visitor/visitor.py`
- [Parsed values](https://github.com/kolesole/rtgl/blob/main/rtgl/visitor/parsed_value.py): `rtgl/visitor/parsed_value.py`

### Validation and schema

- [Validator base](https://github.com/kolesole/rtgl/blob/main/rtgl/validator/validator.py): `rtgl/validator/validator.py`
- [Static validation](https://github.com/kolesole/rtgl/blob/main/rtgl/validator/static_validator.py): `rtgl/validator/static_validator.py`
- [Temporal validation](https://github.com/kolesole/rtgl/blob/main/rtgl/validator/temporal_validator.py): `rtgl/validator/temporal_validator.py`
- [Validation diagnostics](https://github.com/kolesole/rtgl/blob/main/rtgl/validator/diagnostics.py): `rtgl/validator/diagnostics.py`
- [Database explorer](https://github.com/kolesole/rtgl/blob/main/rtgl/base/database_explorer.py): `rtgl/base/database_explorer.py`
- [Path builder](https://github.com/kolesole/rtgl/blob/main/rtgl/base/path_builder.py): `rtgl/base/path_builder.py`

### SQL conversion

- [Converter base](https://github.com/kolesole/rtgl/blob/main/rtgl/converter/converter.py): `rtgl/converter/converter.py`
- [Static converter](https://github.com/kolesole/rtgl/blob/main/rtgl/converter/static_converter.py): `rtgl/converter/static_converter.py`
- [Temporal converter](https://github.com/kolesole/rtgl/blob/main/rtgl/converter/temporal_converter.py): `rtgl/converter/temporal_converter.py`

### Execution and data

- [Relational database](https://github.com/kolesole/rtgl/blob/main/rtgl/base/database.py): `rtgl/base/database.py`
- [Table metadata](https://github.com/kolesole/rtgl/blob/main/rtgl/base/table.py): `rtgl/base/table.py`
- **DuckDB**
- [SQL or result table](https://github.com/kolesole/rtgl/blob/main/rtgl/base/table.py): `rtgl/base/table.py`

### Other components

- **Query author**
- **Prediction timestamps**

## Connections

- Query author → RTGL query: writes
- RTGL query → ANTLR parser: parses
- RTGL grammar → ANTLR parser: defines syntax
- ANTLR parser → Query visitor: provides parse tree
- Query visitor → Parsed values: builds values
- Query visitor → Converter base: returns query model
- Converter base → Validator base: validates
- Validator base → Static validation: uses for static
- Validator base → Temporal validation: uses for temporal
- Validator base → Validation diagnostics: reports issues
- Validator base → Database explorer: resolves schema
- Validator base → Path builder: resolves joins
- Database explorer → Relational database: inspects
- Converter base → Static converter: supports static
- Converter base → Temporal converter: supports temporal
- Static converter → Relational database: reads
- Temporal converter → Relational database: reads
- Prediction timestamps → Temporal converter: sets evaluation times
- Temporal converter → SQL or result table: returns result table
- Static converter → SQL or result table: returns SQL or table
- Temporal converter → DuckDB: executes SQL
- Static converter → DuckDB: executes SQL
- DuckDB → SQL or result table: returns query rows