# samhithpola2025/ivoryscript-v2 architecture

> Architecture diagram of the GitHub repository samhithpola2025/ivoryscript-v2, 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/samhithpola2025/ivoryscript-v2
- Repository: https://github.com/samhithpola2025/ivoryscript-v2

## Overview

IvoryScript is a C++ language front end that currently generates and prints an AST; despite the bytecodevm directory name, the README says it does not execute programs. Users either provide an .ivc file or enter REPL mode. Both paths tokenize source, parse it into a Program AST, and print that AST; the parser also uses scoped symbol tables and shared type helpers. The README documents language syntax and sample programs, but unsampled implementation details are not inferred here.

Main entry points: [`ivoryscript/main.cpp`](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/main.cpp) (CLI Entry), [`ivoryscript/modules/repl/repl.cpp`](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/repl/repl.cpp) (REPL Loop), [`ivoryscript/modules/parser/parser.cpp`](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/parser/parser.cpp) (Parser and AST), [`ivoryscript/modules/bytecodevm/traverser.cpp`](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/bytecodevm/traverser.cpp) (AST Printer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Modes"]
  node_main["CLI Entry<br/>[main.cpp]"]
  node_repl["REPL Loop<br/>[repl.cpp]"]
end

subgraph group_frontend["Language Front End"]
  node_tokenizer["Tokenizer<br/>[tokenizer.cpp]"]
  node_parser["Parser and AST<br/>[parser.cpp]"]
end

subgraph group_support["Parser Support"]
  node_symtab["Scoped Symbols<br/>[symtab.cpp]"]
  node_helpers["Language Helpers<br/>[helpers.cpp]"]
end

subgraph group_output["AST Output"]
  node_traverser["AST Printer<br/>[traverser.cpp]"]
end

node_file_user(("File User"))
node_terminal_user(("REPL User"))
node_console(("Terminal Output"))

node_file_user -->|"provides file"| node_main
node_terminal_user -->|"enters source"| node_repl
node_main -->|"starts when no file"| node_repl
node_main -->|"tokenizes file"| node_tokenizer
node_tokenizer -->|"supplies tokens"| node_parser
node_main -->|"parses tokens"| node_parser
node_main -->|"prints AST"| node_traverser
node_repl -->|"tokenizes input"| node_tokenizer
node_repl -->|"parses tokens"| node_parser
node_repl -->|"prints AST"| node_traverser
node_parser -->|"resolves symbols"| node_symtab
node_parser -->|"maps types"| node_helpers
node_traverser -->|"formats operators"| node_helpers
node_traverser -->|"writes AST"| node_console

click node_main "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/main.cpp"
click node_repl "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/repl/repl.cpp"
click node_tokenizer "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/tokenizer/tokenizer.cpp"
click node_parser "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/parser/parser.cpp"
click node_traverser "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/bytecodevm/traverser.cpp"
click node_symtab "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/parser/symtab.cpp"
click node_helpers "https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/helpers/helpers.cpp"

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_main,node_repl,node_file_user,node_terminal_user toneBlue
class node_tokenizer,node_parser toneAmber
class node_symtab,node_helpers toneMint
class node_traverser toneRose
class node_console toneIndigo
```

## Components

### Entry Modes

- [CLI Entry](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/main.cpp): `ivoryscript/main.cpp`
- [REPL Loop](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/repl/repl.cpp): `ivoryscript/modules/repl/repl.cpp`

### Language Front End

- [Tokenizer](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/tokenizer/tokenizer.cpp): `ivoryscript/modules/tokenizer/tokenizer.cpp`
- [Parser and AST](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/parser/parser.cpp): `ivoryscript/modules/parser/parser.cpp`

### Parser Support

- [Scoped Symbols](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/parser/symtab.cpp): `ivoryscript/modules/parser/symtab.cpp`
- [Language Helpers](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/helpers/helpers.cpp): `ivoryscript/modules/helpers/helpers.cpp`

### AST Output

- [AST Printer](https://github.com/samhithpola2025/ivoryscript-v2/blob/main/ivoryscript/modules/bytecodevm/traverser.cpp): `ivoryscript/modules/bytecodevm/traverser.cpp`

### Other components

- **File User**
- **REPL User**
- **Terminal Output**

## Connections

- File User → CLI Entry: provides file
- REPL User → REPL Loop: enters source
- CLI Entry → REPL Loop: starts when no file
- CLI Entry → Tokenizer: tokenizes file
- Tokenizer → Parser and AST: supplies tokens
- CLI Entry → Parser and AST: parses tokens
- CLI Entry → AST Printer: prints AST
- REPL Loop → Tokenizer: tokenizes input
- REPL Loop → Parser and AST: parses tokens
- REPL Loop → AST Printer: prints AST
- Parser and AST → Scoped Symbols: resolves symbols
- Parser and AST → Language Helpers: maps types
- AST Printer → Language Helpers: formats operators
- AST Printer → Terminal Output: writes AST