# thamizh-arasu/uttr architecture

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

- Interactive diagram: https://gitdiagram.com/thamizh-arasu/uttr
- Repository: https://github.com/thamizh-arasu/uttr

## Overview

UTTR is a single-language interpreter repository, organized around a classic source-to-execution pipeline with a few important runtime subsystems layered around it.

At the highest level, the repository splits into four major architectural zones:

1. Language front end
2. Runtime/object model
3. Module and standard library loading
4. Developer-facing execution and verification tools

#### 1) Language front end: source text to AST

The front end is built from the usual interpreter stages:

- `lexer.py` turns raw `.uttr` source into tokens.
- `parser.py` consumes tokens and builds an abstract syntax tree.
- `nodes/` contains the AST node types used by the parser and interpreter.

This is a handwritten language implementation in Python, not a generated parser or compiler. The grammar supports a procedure-oriented, English-like syntax with constructs such as:

- variable and constant binding
- conditionals
- `check...whether...default` switch cases
- `cycle`, `as long as`, and `repeat while` loops
- function definitions and calls
- lambdas
- list, tuple, set, dict, string, and regex literals
- `attempt...handle` error handling
- `bring in` / `share` module statements
- `cut` and `skip` loop control

The AST node files show the grammar shape clearly: there are dedicated node classes for all major expressions and statements, such as `if_node.py`, `for_node.py`, `while_node.py`, `function_definition_node.py`, `attempt_handle_node.py`, `switch_case_node.py`, and the literal/access nodes for collections and primitives.

A useful diagram boundary is that the parser does not execute anything; it only produces a tree of node objects. Those node objects are then handed to the interpreter.

#### 2) Runtime execution: AST to values and side effects

The runtime center is `interpreter.py`. It walks the AST and evaluates nodes in the current execution context.

The interpreter depends on a small set of runtime infrastructure classes:

- `context.py` for call/context state
- `symbol_table.py` for variable and constant resolution
- `position.py` for source location tracking
- `run_time_result.py` for propagating success, return, break/continue, and errors
- `parse_result.py` for parser success/error propagation

This architecture means execution state is explicit and scoped. A context owns a symbol table and can link to a parent context, which is how function calls and module execution keep their own scope while still reaching outer symbols when appropriate.

The runtime value system is separated into `values/`:

- `number_value.py`
- `string_value.py`
- `list_value.py`
- `tuple_value.py`
- `set_value.py`
- `dict_value.py`
- `regex_value.py`
- `error_value.py`
- `value.py` as the common base

This is a strong architectural boundary: the interpreter does not manipulate Python primitive types directly once execution starts. Instead, each UTTR type has its own runtime object with behavior such as arithmetic, comparison, indexing, mutation, and stringification. That makes it much easier to reason about language semantics, immutability, and operator overloading.

The `functions/` package provides the callable abstraction:

- `base_function.py` defines the common interface
- `function.py` handles user-defined UTTR functions
- `builtin_function.py` handles built-in functions like I/O, collection helpers, regex helpers, and `run`

This means function invocation is unified at runtime regardless of whether a function originated from UTTR source or was provided by the runtime.

#### 3) Module system and standard library

Modules are a first-class subsystem, not a thin import wrapper.

Key files:

- `module.py`
- `module_loader.py`
- `module_config.py`

The README and file structure indicate a module system with:

- `bring in` for whole-module imports
- selective imports with aliases
- `share` for explicit exports
- automatic export of top-level definitions when not hidden by underscore naming
- module caching
- circular import detection
- path resolution across current file directory, current working directory, and `stdlib/`

This subsystem is important architecturally because imported functions preserve their defining context. That means a function imported from a module can still see other module-local symbols when invoked elsewhere. So a module is not just copied text; it behaves like a separately executed namespace with retained runtime identity.

The `stdlib/` directory contains UTTR-authored standard library modules:

- `math.uttr`
- `lists.uttr`
- `strings.uttr`

These are part of the language distribution but are implemented in the language itself rather than in Python, which makes the module system both a user feature and a bootstrap mechanism for reusable libraries.

The module system is also a boundary between user code and language-provided code. The loader resolves imports, executes modules once, and reuses cached module state afterward.

#### 4) Errors and diagnostics

The `errors/` package defines the error hierarchy:

- `error.py` as the base
- `illegal_character.py`
- `invalid_syntax.py`
- `run_time_error.py`
- `module_not_found_error.py`
- `circular_import_error.py`

This separates lexical, parse, runtime, and module-resolution failures. Source-position-aware reporting is a major design goal, supported by `position.py` and `strings_with_arrows.py`, which produces the caret/arrow-style diagnostics shown in the README.

The runtime also supports UTTR-level error handling via `attempt...handle`, and `values/error_value.py` suggests caught errors are reified as runtime values with fields like message and type. That means there are two related error paths:

- engine-internal errors used to stop or report the interpreter
- language-level caught errors exposed to UTTR programs as values

That distinction is important for diagramming: not every error terminates execution immediately; some are intentionally captured and handled in the language.

#### 5) Entry points and execution surfaces

There are two main execution surfaces:

- `entry.py` as the orchestration entry point
- `shell.py` as the REPL / command-line runner

`entry.py` likely wires together lexer, parser, interpreter, and the initial global symbol table setup. `shell.py` adds user interaction: running files or starting an interactive REPL session.

`lexer_testing.py` is a separate tool for token inspection and lexer diagnostics.

So, from an architecture diagram perspective, the typical flow is:

- source file or REPL input
- lexer
- parser
- AST
- interpreter
- runtime values / symbol tables / contexts
- output or errors

#### 6) Repository structure as a product boundary

The repository clearly contains both implementation and specification assets:

- `examples/` demonstrates language features and serves as executable documentation
- `tests/` contains a substantial `.uttr` test suite and a Python runner
- `debug/` stores targeted regression cases and lexer/parser behavior samples
- `docs/` contains design notes for regex and import-context behavior
- `assets/` contains branding/logo material, not part of execution

The tests are especially informative architecturally: they cover language semantics rather than just unit-testing small functions. That suggests the project is validated primarily through end-to-end execution of source programs through the full interpreter pipeline.

#### 7) Main data flows

##### Source execution flow
1. A `.uttr` program enters through `shell.py` or `entry.py`.
2. `lexer.py` tokenizes source text using keyword definitions from `tokens.py` and character classes from `constants.py`.
3. `parser.py` transforms tokens into AST nodes from `nodes/`.
4. `interpreter.py` evaluates the AST.
5. Evaluation reads/writes `symbol_table.py` inside a `context.py`.
6. Values are represented by classes in `values/`.
7. Built-in and user-defined calls are unified through `functions/`.
8. Errors propagate through result wrappers and the error hierarchy.

##### Module import flow
1. An import statement reaches the interpreter.
2. The module loader resolves the target path.
3. The target module is parsed and executed in its own context.
4. Exported symbols are cached and exposed to the importing program.
5. Circular dependencies and missing modules are detected and reported as specialized errors.

##### Error flow
1. The lexer/parser/interpreter raises or returns a structured error.
2. Position metadata from `position.py` is attached.
3. `strings_with_arrows.py` formats readable source excerpts.
4. For `attempt...handle`, runtime errors can be wrapped into `error_value.py` and handled inside the language.

#### 8) Technologies and operational profile

This is a pure Python project targeting Python 3.7+ and uses only the Python standard library. That matters architecturally because the runtime is self-contained: parsing, execution, modules, regex support, and tests all live inside the repository without external dependencies.

Regular expressions are implemented with Python’s `re` module under the hood, but exposed through UTTR syntax and runtime values. The README shows this is treated as a language feature, not a library addon.

#### 9) How to think about the architecture diagram

If you are drawing a diagram, the cleanest set of boxes is:

- Input surface: REPL / file runner
- Language front end: lexer + parser + AST nodes
- Runtime engine: interpreter + execution result handling
- Runtime state: contexts + symbol tables + values + functions
- Module system: loader + config + standard library modules
- Diagnostics: error classes + arrow-based source rendering
- Validation content: examples + tests + debug cases

The important boundaries are:
- syntax processing versus execution
- user-defined values versus Python host objects
- normal program flow versus error-handling flow
- local module namespace versus imported/exported symbol visibility
- built-in runtime functions versus UTTR-authored stdlib modules

Overall, UTTR is a compact but fully layered interpreter platform, with a clear separation between language parsing, runtime semantics, module loading, and test/example content.

Main entry points: [`interpreter.py`](https://github.com/thamizh-arasu/uttr/blob/HEAD/interpreter.py) (Interpreter), [`entry.py`](https://github.com/thamizh-arasu/uttr/blob/HEAD/entry.py) (Entry), [`module_loader.py`](https://github.com/thamizh-arasu/uttr/blob/HEAD/module_loader.py) (Modules), [`lexer.py`](https://github.com/thamizh-arasu/uttr/blob/HEAD/lexer.py) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Language front end"
  node_lexer["Lexer<br/>scanner<br/>[lexer.py]"]
  node_parser["Parser<br/>[parser.py]"]
  node_nodes["AST nodes<br/>syntax tree<br/>[if_node.py]"]
end

subgraph "Runtime engine"
  node_interpreter["Interpreter<br/>executor<br/>[interpreter.py]"]
  node_context["Context<br/>execution scope<br/>[context.py]"]
  node_symbols["Symbols<br/>symbol table<br/>[symbol_table.py]"]
  node_run_result["Run result<br/>flow control<br/>[run_time_result.py]"]
  node_values[("Values<br/>runtime types<br/>[value.py]")]
  node_functions["Functions<br/>callable runtime<br/>[base_function.py]"]
end

subgraph "Module system"
  node_modules["Modules<br/>import system<br/>[module_loader.py]"]
  node_module["Module model<br/>module state<br/>[module.py]"]
  node_stdlib["Stdlib<br/>uttr library<br/>[math.uttr]"]
end

subgraph "Diagnostics"
  node_errors["Errors<br/>diagnostics<br/>[error.py]"]
  node_arrows["Arrows<br/>reporting"]
end

subgraph "Execution tools"
  node_entry["Entry<br/>orchestrator<br/>[entry.py]"]
  node_shell["Shell<br/>cli/repl<br/>[shell.py]"]
end

subgraph "Repo content"
  node_tests["Tests<br/>validation<br/>[run_tests.py]"]
  node_examples["Examples<br/>samples<br/>[functions.uttr]"]
  node_debug["Debug cases<br/>regression corpus"]
  node_docs["Docs<br/>design notes<br/>[regex_design.md]"]
end

node_entry -->|"starts"| node_lexer
node_entry -->|"wires"| node_parser
node_entry -->|"runs"| node_interpreter
node_shell -->|"delegates"| node_entry
node_lexer -->|"tokens"| node_parser
node_parser -->|"builds"| node_nodes
node_nodes -->|"executed by"| node_interpreter
node_interpreter -->|"uses"| node_context
node_context -->|"owns"| node_symbols
node_interpreter -->|"propagates"| node_run_result
node_interpreter -->|"produces"| node_values
node_functions -->|"returns"| node_values
node_interpreter -->|"invokes"| node_functions
node_modules -->|"creates"| node_module
node_modules -->|"loads"| node_stdlib
node_interpreter -->|"imports"| node_modules
node_modules -->|"scopes"| node_context
node_errors -->|"formats"| node_arrows
node_lexer -->|"reports"| node_errors
node_parser -->|"reports"| node_errors
node_interpreter -->|"reports"| node_errors
node_tests -->|"executes"| node_entry
node_examples -->|"demonstrates"| node_entry
node_debug -->|"probes"| node_lexer
node_docs -->|"describes"| node_modules

click node_entry "https://github.com/thamizh-arasu/uttr/blob/main/entry.py"
click node_shell "https://github.com/thamizh-arasu/uttr/blob/main/shell.py"
click node_lexer "https://github.com/thamizh-arasu/uttr/blob/main/lexer.py"
click node_parser "https://github.com/thamizh-arasu/uttr/blob/main/parser.py"
click node_nodes "https://github.com/thamizh-arasu/uttr/blob/main/nodes/if_node.py"
click node_interpreter "https://github.com/thamizh-arasu/uttr/blob/main/interpreter.py"
click node_context "https://github.com/thamizh-arasu/uttr/blob/main/context.py"
click node_symbols "https://github.com/thamizh-arasu/uttr/blob/main/symbol_table.py"
click node_run_result "https://github.com/thamizh-arasu/uttr/blob/main/run_time_result.py"
click node_values "https://github.com/thamizh-arasu/uttr/blob/main/values/value.py"
click node_functions "https://github.com/thamizh-arasu/uttr/blob/main/functions/base_function.py"
click node_modules "https://github.com/thamizh-arasu/uttr/blob/main/module_loader.py"
click node_module "https://github.com/thamizh-arasu/uttr/blob/main/module.py"
click node_stdlib "https://github.com/thamizh-arasu/uttr/blob/main/stdlib/math.uttr"
click node_errors "https://github.com/thamizh-arasu/uttr/blob/main/errors/error.py"
click node_arrows "https://github.com/thamizh-arasu/uttr/blob/main/strings_with_arrows.py"
click node_tests "https://github.com/thamizh-arasu/uttr/blob/main/tests/run_tests.py"
click node_examples "https://github.com/thamizh-arasu/uttr/blob/main/examples/functions.uttr"
click node_debug "https://github.com/thamizh-arasu/uttr/blob/main/debug/test_lambda_basic.uttr"
click node_docs "https://github.com/thamizh-arasu/uttr/blob/main/docs/regex_design.md"

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_parser,node_nodes toneBlue
class node_interpreter,node_context,node_symbols,node_run_result,node_values,node_functions toneAmber
class node_modules,node_module,node_stdlib toneMint
class node_errors,node_arrows toneRose
class node_entry,node_shell toneIndigo
class node_tests,node_examples,node_debug,node_docs toneTeal
```

## Components

### Language front end

Tokenization, parsing, and AST construction.

- [Lexer](https://github.com/thamizh-arasu/uttr/blob/HEAD/lexer.py): scanner · Turns UTTR source text into tokens. · `lexer.py`
- [Parser](https://github.com/thamizh-arasu/uttr/blob/HEAD/parser.py): parser · Consumes tokens and builds AST nodes. · `parser.py`
- [AST nodes](https://github.com/thamizh-arasu/uttr/blob/HEAD/nodes/if_node.py): syntax tree · Node classes representing UTTR expressions and statements. · `nodes/if_node.py`

### Runtime engine

Execution state, values, and callable abstractions.

- [Interpreter](https://github.com/thamizh-arasu/uttr/blob/HEAD/interpreter.py): executor · Evaluates the AST and drives program execution. · `interpreter.py`
- [Context](https://github.com/thamizh-arasu/uttr/blob/HEAD/context.py): execution scope · Holds call/module execution state and links to parent scopes. · `context.py`
- [Symbols](https://github.com/thamizh-arasu/uttr/blob/HEAD/symbol_table.py): symbol table · Resolves variables and constants within a context. · `symbol_table.py`
- [Run result](https://github.com/thamizh-arasu/uttr/blob/HEAD/run_time_result.py): flow control · Propagates returns, breaks, continues, and runtime errors. · `run_time_result.py`
- [Values](https://github.com/thamizh-arasu/uttr/blob/HEAD/values/value.py): runtime types · UTTR value objects such as numbers, strings, collections, regexes, and errors. · `values/value.py`
- [Functions](https://github.com/thamizh-arasu/uttr/blob/HEAD/functions/base_function.py): callable runtime · Unifies user-defined and built-in callable behavior. · `functions/base_function.py`

### Module system

Import resolution, caching, and stdlib loading.

- [Modules](https://github.com/thamizh-arasu/uttr/blob/HEAD/module_loader.py): import system · Resolves, loads, caches, and exposes imported modules. · `module_loader.py`
- [Module model](https://github.com/thamizh-arasu/uttr/blob/HEAD/module.py): module state · Represents a loaded module and its exported namespace. · `module.py`
- [Stdlib](https://github.com/thamizh-arasu/uttr/blob/HEAD/stdlib/math.uttr): uttr library · UTTR-authored standard library modules for math, lists, and strings. · `stdlib/math.uttr`

### Diagnostics

Error types and source-aware reporting.

- [Errors](https://github.com/thamizh-arasu/uttr/blob/HEAD/errors/error.py): diagnostics · Lexical, syntax, runtime, and import-related error hierarchy. · `errors/error.py`
- [Arrows](https://github.com/thamizh-arasu/uttr/blob/HEAD/strings_with_arrows.py): reporting · Formats source excerpts with caret-style diagnostics. · `strings_with_arrows.py`

### Execution tools

Entry points, REPL, and test harnesses.

- [Entry](https://github.com/thamizh-arasu/uttr/blob/HEAD/entry.py): orchestrator · Bootstraps lexing, parsing, interpretation, and runtime setup. · `entry.py`
- [Shell](https://github.com/thamizh-arasu/uttr/blob/HEAD/shell.py): cli/repl · Interactive runner and command-line execution surface. · `shell.py`

### Repo content

Examples, tests, docs, and debug programs.

- [Tests](https://github.com/thamizh-arasu/uttr/blob/HEAD/tests/run_tests.py): validation · End-to-end UTTR test programs and the Python test runner. · `tests/run_tests.py`
- [Examples](https://github.com/thamizh-arasu/uttr/blob/HEAD/examples/functions.uttr): samples · Executable language examples and usage demonstrations. · `examples/functions.uttr`
- [Debug cases](https://github.com/thamizh-arasu/uttr/blob/HEAD/debug/test_lambda_basic.uttr): regression corpus · Targeted lexer/parser/runtime edge cases and reproductions. · `debug/test_lambda_basic.uttr`
- [Docs](https://github.com/thamizh-arasu/uttr/blob/HEAD/docs/regex_design.md): design notes · Architecture notes for imports and regex behavior. · `docs/regex_design.md`

## Connections

- Entry → Lexer: starts · Orchestration begins by scanning source text.
- Entry → Parser: wires · Entry point feeds lexer output into parsing.
- Entry → Interpreter: runs · Initializes execution of the parsed program.
- Shell → Entry: delegates · Shell uses the entry pipeline for file execution and REPL actions.
- Lexer → Parser: tokens · Parser consumes lexer-produced tokens.
- Parser → AST nodes: builds · Parser instantiates AST node objects.
- AST nodes → Interpreter: executed by · Interpreter evaluates AST node types.
- Interpreter → Context: uses · Execution occurs within a scoped context.
- Context → Symbols: owns · Each context carries symbol storage.
- Interpreter → Run result: propagates · Evaluation returns structured flow-control results.
- Interpreter → Values: produces · Runtime semantics operate on UTTR value objects.
- Functions → Values: returns · Callable execution yields runtime values.
- Interpreter → Functions: invokes · User and built-in calls share one callable abstraction.
- Modules → Module model: creates · Loader materializes module instances and cached state.
- Modules → Stdlib: loads · Loader resolves UTTR standard library modules.
- Interpreter → Modules: imports · Import nodes trigger module resolution and execution.
- Modules → Context: scopes · Modules execute in their own linked context.
- Errors → Arrows: formats · Error reporting is rendered with source arrows.
- Lexer → Errors: reports · Illegal character failures surface as lexical errors.
- Parser → Errors: reports · Syntax failures surface as parser errors.
- Interpreter → Errors: reports · Runtime failures and import failures become structured errors.
- Tests → Entry: executes · The test harness runs programs through the interpreter pipeline.
- Examples → Entry: demonstrates · Examples are executable inputs for the main pipeline.
- Debug cases → Lexer: probes · Debug cases focus on lexing and parser edge cases.
- Docs → Modules: describes · Design notes document import and regex behavior.
