# pyrotek45/avon architecture

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

- Interactive diagram: https://gitdiagram.com/pyrotek45/avon
- Repository: https://github.com/pyrotek45/avon

## Overview

Avon is a functional text-template language and CLI: users evaluate programs to preview generated files or deploy them, and can also run shell tasks. Its runtime includes a lexer, parser, evaluator, and built-ins; the CLI adds interactive use, deployment, task execution, and documentation. An optional editor path connects VS Code to an LSP server that reuses Avon’s language implementation. The README describes deployment preflight and Git integration; source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/cli/commands.rs`](https://github.com/pyrotek45/avon/blob/main/src/cli/commands.rs) (CLI commands), [`src/eval/mod.rs`](https://github.com/pyrotek45/avon/blob/main/src/eval/mod.rs) (Evaluator), [`src/cli/repl/commands.rs`](https://github.com/pyrotek45/avon/blob/main/src/cli/repl/commands.rs) (Interactive REPL), [`avon-lsp/src/main.rs`](https://github.com/pyrotek45/avon/blob/main/avon-lsp/src/main.rs) (Language server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language runtime"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_eval["Evaluator<br/>[mod.rs]"]
  node_common["Language values<br/>[common.rs]"]
  node_builtin_registry["Builtin registry<br/>[registry.rs]"]
  node_file_builtins["File built-ins<br/>[file_io.rs]"]
  node_git_fetch["Git fetch<br/>[mod.rs]"]
end

subgraph group_cli["CLI workflows"]
  node_avon_main["CLI entry<br/>[main.rs]"]
  node_commands["CLI commands<br/>[commands.rs]"]
  node_repl["Interactive REPL<br/>[commands.rs]"]
  node_repl_state["REPL state<br/>[state.rs]"]
  node_deployment["Deployment<br/>[deployment.rs]"]
  node_task_runner["Task runner<br/>[task_runner.rs]"]
  node_cli_docs["Builtin docs<br/>[docs.rs]"]
end

subgraph group_editor["Editor integration"]
  node_vscode_ext["VS Code extension<br/>[extension.ts]"]
  node_lsp["Language server<br/>[main.rs]"]
end

subgraph group_external["External effects"]
  node_filesystem[("Local filesystem")]
  node_shell["Shell tasks"]
  node_git_remote["Git hosting"]
end

node_user(("User"))
node_editor(("VS Code user"))

node_user -->|"runs CLI"| node_avon_main
node_avon_main -->|"dispatches"| node_commands
node_commands -->|"tokenizes source"| node_lexer
node_commands -->|"parses tokens"| node_parser
node_commands -->|"evaluates program"| node_eval
node_lexer -->|"returns tokens"| node_parser
node_parser -->|"returns AST"| node_eval
node_eval -->|"uses values"| node_common
node_eval -->|"loads built-ins"| node_builtin_registry
node_builtin_registry -->|"registers"| node_file_builtins
node_commands -->|"deploys result"| node_deployment
node_deployment -->|"writes files"| node_filesystem
node_commands -->|"runs tasks"| node_task_runner
node_task_runner -->|"executes tasks"| node_shell
node_commands -->|"shows help"| node_cli_docs
node_user -->|"enters REPL"| node_repl
node_repl -->|"updates state"| node_repl_state
node_repl -->|"processes source"| node_commands
node_repl -->|"deploys result"| node_deployment
node_editor -->|"opens Avon"| node_vscode_ext
node_vscode_ext -->|"starts server"| node_lsp
node_lsp -->|"tokenizes documents"| node_lexer
node_lsp -->|"checks syntax"| node_parser
node_lsp -->|"validates programs"| node_eval
node_eval -.->|"fetches remote source"| node_git_fetch
node_git_fetch -.->|"requests content"| node_git_remote
node_eval -->|"executes file operations"| node_file_builtins
node_file_builtins -->|"reads files"| node_filesystem

click node_avon_main "https://github.com/pyrotek45/avon/blob/main/src/main.rs"
click node_commands "https://github.com/pyrotek45/avon/blob/main/src/cli/commands.rs"
click node_repl "https://github.com/pyrotek45/avon/blob/main/src/cli/repl/commands.rs"
click node_repl_state "https://github.com/pyrotek45/avon/blob/main/src/cli/repl/state.rs"
click node_deployment "https://github.com/pyrotek45/avon/blob/main/src/cli/deployment.rs"
click node_task_runner "https://github.com/pyrotek45/avon/blob/main/src/cli/task_runner.rs"
click node_cli_docs "https://github.com/pyrotek45/avon/blob/main/src/cli/docs.rs"
click node_lexer "https://github.com/pyrotek45/avon/blob/main/src/lexer.rs"
click node_parser "https://github.com/pyrotek45/avon/blob/main/src/parser.rs"
click node_eval "https://github.com/pyrotek45/avon/blob/main/src/eval/mod.rs"
click node_common "https://github.com/pyrotek45/avon/blob/main/src/common.rs"
click node_builtin_registry "https://github.com/pyrotek45/avon/blob/main/src/eval/builtins/registry.rs"
click node_file_builtins "https://github.com/pyrotek45/avon/blob/main/src/eval/builtins/file_io.rs"
click node_git_fetch "https://github.com/pyrotek45/avon/blob/main/src/eval/mod.rs"
click node_vscode_ext "https://github.com/pyrotek45/avon/blob/main/vscode/src/extension.ts"
click node_lsp "https://github.com/pyrotek45/avon/blob/main/avon-lsp/src/main.rs"

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_eval,node_common,node_builtin_registry,node_file_builtins,node_git_fetch,node_user,node_editor toneBlue
class node_avon_main,node_commands,node_repl,node_repl_state,node_deployment,node_task_runner,node_cli_docs toneAmber
class node_vscode_ext,node_lsp toneMint
class node_filesystem,node_shell,node_git_remote toneRose
```

## Components

### Language runtime

- [Lexer](https://github.com/pyrotek45/avon/blob/main/src/lexer.rs): `src/lexer.rs`
- [Parser](https://github.com/pyrotek45/avon/blob/main/src/parser.rs): `src/parser.rs`
- [Evaluator](https://github.com/pyrotek45/avon/blob/main/src/eval/mod.rs): `src/eval/mod.rs`
- [Language values](https://github.com/pyrotek45/avon/blob/main/src/common.rs): `src/common.rs`
- [Builtin registry](https://github.com/pyrotek45/avon/blob/main/src/eval/builtins/registry.rs): `src/eval/builtins/registry.rs`
- [File built-ins](https://github.com/pyrotek45/avon/blob/main/src/eval/builtins/file_io.rs): `src/eval/builtins/file_io.rs`
- [Git fetch](https://github.com/pyrotek45/avon/blob/main/src/eval/mod.rs): `src/eval/mod.rs`

### CLI workflows

- [CLI entry](https://github.com/pyrotek45/avon/blob/main/src/main.rs): `src/main.rs`
- [CLI commands](https://github.com/pyrotek45/avon/blob/main/src/cli/commands.rs): `src/cli/commands.rs`
- [Interactive REPL](https://github.com/pyrotek45/avon/blob/main/src/cli/repl/commands.rs): `src/cli/repl/commands.rs`
- [REPL state](https://github.com/pyrotek45/avon/blob/main/src/cli/repl/state.rs): `src/cli/repl/state.rs`
- [Deployment](https://github.com/pyrotek45/avon/blob/main/src/cli/deployment.rs): `src/cli/deployment.rs`
- [Task runner](https://github.com/pyrotek45/avon/blob/main/src/cli/task_runner.rs): `src/cli/task_runner.rs`
- [Builtin docs](https://github.com/pyrotek45/avon/blob/main/src/cli/docs.rs): `src/cli/docs.rs`

### Editor integration

- [VS Code extension](https://github.com/pyrotek45/avon/blob/main/vscode/src/extension.ts): `vscode/src/extension.ts`
- [Language server](https://github.com/pyrotek45/avon/blob/main/avon-lsp/src/main.rs): `avon-lsp/src/main.rs`

### External effects

- **Local filesystem**
- **Shell tasks**
- **Git hosting**

### Other components

- **User**
- **VS Code user**

## Connections

- User → CLI entry: runs CLI
- CLI entry → CLI commands: dispatches
- CLI commands → Lexer: tokenizes source
- CLI commands → Parser: parses tokens
- CLI commands → Evaluator: evaluates program
- Lexer → Parser: returns tokens
- Parser → Evaluator: returns AST
- Evaluator → Language values: uses values
- Evaluator → Builtin registry: loads built-ins
- Builtin registry → File built-ins: registers
- CLI commands → Deployment: deploys result
- Deployment → Local filesystem: writes files
- CLI commands → Task runner: runs tasks
- Task runner → Shell tasks: executes tasks
- CLI commands → Builtin docs: shows help
- User → Interactive REPL: enters REPL
- Interactive REPL → REPL state: updates state
- Interactive REPL → CLI commands: processes source
- Interactive REPL → Deployment: deploys result
- VS Code user → VS Code extension: opens Avon
- VS Code extension → Language server: starts server
- Language server → Lexer: tokenizes documents
- Language server → Parser: checks syntax
- Language server → Evaluator: validates programs
- Evaluator → Git fetch: fetches remote source
- Git fetch → Git hosting: requests content
- Evaluator → File built-ins: executes file operations
- File built-ins → Local filesystem: reads files