# sxijyoti/lexicon architecture

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

- Interactive diagram: https://gitdiagram.com/sxijyoti/lexicon
- Repository: https://github.com/sxijyoti/lexicon

## Overview

Lexicon is a Go interpreter for Sprout. Users enter expressions in the REPL or run Sprout files; the interpreter tokenizes source, parses it into an AST, evaluates it in an environment, and prints results or errors. The REPL also exposes environment inspection and trace controls. The main execution path is supported by the REPL and parser excerpts; the file-runner path is documented but its implementation was not sampled, so its links are documented rather than source-verified.

Main entry points: [`cmd/repl/main.go`](https://github.com/sxijyoti/lexicon/blob/main/cmd/repl/main.go) (Interactive REPL), [`src/evaluator/evaluator.go`](https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/evaluator.go) (Evaluator), [`src/lexer/lexer.go`](https://github.com/sxijyoti/lexicon/blob/main/src/lexer/lexer.go) (Lexer), [`src/parser/parser.go`](https://github.com/sxijyoti/lexicon/blob/main/src/parser/parser.go) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_repl["Interactive REPL<br/>[main.go]"]
  node_file_runner["File Runner"]
end

subgraph group_language["Language Front End"]
  node_lexer["Lexer<br/>[lexer.go]"]
  node_tokens["Token Definitions<br/>[token.go]"]
  node_parser["Parser<br/>[parser.go]"]
  node_ast["AST Nodes<br/>[ast.go]"]
end

subgraph group_runtime["Interpreter Runtime"]
  node_evaluator["Evaluator<br/>[evaluator.go]"]
  node_environment["Variable Environment<br/>[environment.go]"]
  node_runtime_values["Runtime Values<br/>[object.go]"]
end

subgraph group_diagnostics["Diagnostics"]
  node_logger["Trace Logger<br/>[logger.go]"]
end

node_user(("Sprout User"))

node_user -->|"enters expressions"| node_repl
node_user -->|"runs source files"| node_file_runner
node_repl -->|"creates environment"| node_environment
node_repl -->|"tokenizes input"| node_lexer
node_repl -->|"parses tokens"| node_parser
node_repl -->|"evaluates program"| node_evaluator
node_repl -->|"toggles tracing"| node_logger
node_lexer -->|"emits tokens"| node_tokens
node_parser -->|"reads tokens"| node_lexer
node_parser -->|"builds syntax tree"| node_ast
node_evaluator -->|"evaluates nodes"| node_ast
node_evaluator -->|"reads and writes"| node_environment
node_evaluator -->|"creates values"| node_runtime_values
node_evaluator -->|"emits trace"| node_logger
node_file_runner -.->|"starts interpreter pipeline"| node_lexer

click node_repl "https://github.com/sxijyoti/lexicon/blob/main/cmd/repl/main.go"
click node_file_runner "https://github.com/sxijyoti/lexicon/tree/main/cmd/demo"
click node_lexer "https://github.com/sxijyoti/lexicon/blob/main/src/lexer/lexer.go"
click node_tokens "https://github.com/sxijyoti/lexicon/blob/main/src/token/token.go"
click node_parser "https://github.com/sxijyoti/lexicon/blob/main/src/parser/parser.go"
click node_ast "https://github.com/sxijyoti/lexicon/blob/main/src/ast/ast.go"
click node_evaluator "https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/evaluator.go"
click node_environment "https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/environment.go"
click node_runtime_values "https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/object.go"
click node_logger "https://github.com/sxijyoti/lexicon/blob/main/src/logger/logger.go"

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_repl,node_file_runner,node_user toneBlue
class node_lexer,node_tokens,node_parser,node_ast toneAmber
class node_evaluator,node_environment,node_runtime_values toneMint
class node_logger toneRose
```

## Components

### User Interfaces

- [Interactive REPL](https://github.com/sxijyoti/lexicon/blob/main/cmd/repl/main.go): `cmd/repl/main.go`
- [File Runner](https://github.com/sxijyoti/lexicon/tree/main/cmd/demo): `cmd/demo`

### Language Front End

- [Lexer](https://github.com/sxijyoti/lexicon/blob/main/src/lexer/lexer.go): `src/lexer/lexer.go`
- [Token Definitions](https://github.com/sxijyoti/lexicon/blob/main/src/token/token.go): `src/token/token.go`
- [Parser](https://github.com/sxijyoti/lexicon/blob/main/src/parser/parser.go): `src/parser/parser.go`
- [AST Nodes](https://github.com/sxijyoti/lexicon/blob/main/src/ast/ast.go): `src/ast/ast.go`

### Interpreter Runtime

- [Evaluator](https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/evaluator.go): `src/evaluator/evaluator.go`
- [Variable Environment](https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/environment.go): `src/evaluator/environment.go`
- [Runtime Values](https://github.com/sxijyoti/lexicon/blob/main/src/evaluator/object.go): `src/evaluator/object.go`

### Diagnostics

- [Trace Logger](https://github.com/sxijyoti/lexicon/blob/main/src/logger/logger.go): `src/logger/logger.go`

### Other components

- **Sprout User**

## Connections

- Sprout User → Interactive REPL: enters expressions (evidence: `README.md`)
- Sprout User → File Runner: runs source files (evidence: `README.md`)
- Interactive REPL → Variable Environment: creates environment (evidence: `cmd/repl/main.go`)
- Interactive REPL → Lexer: tokenizes input (evidence: `cmd/repl/main.go`)
- Interactive REPL → Parser: parses tokens (evidence: `cmd/repl/main.go`)
- Interactive REPL → Evaluator: evaluates program (evidence: `cmd/repl/main.go`)
- Interactive REPL → Trace Logger: toggles tracing (evidence: `cmd/repl/main.go`)
- Lexer → Token Definitions: emits tokens (evidence: `src/lexer/lexer.go`)
- Parser → Lexer: reads tokens (evidence: `src/parser/parser.go`)
- Parser → AST Nodes: builds syntax tree (evidence: `src/parser/parser.go`)
- Evaluator → AST Nodes: evaluates nodes (evidence: `src/evaluator/evaluator.go`)
- Evaluator → Variable Environment: reads and writes (evidence: `src/evaluator/evaluator.go`)
- Evaluator → Runtime Values: creates values (evidence: `src/evaluator/evaluator.go`)
- Evaluator → Trace Logger: emits trace (evidence: `src/evaluator/evaluator.go`)
- File Runner → Lexer: starts interpreter pipeline (evidence: `README.md`)
