# ruarq/br4in architecture

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

- Interactive diagram: https://gitdiagram.com/ruarq/br4in
- Repository: https://github.com/ruarq/br4in

## Overview

Br4in is a C++ Brainfuck interpreter with two entry modes: run a source file or interact through a REPL. Both ultimately execute bytecode in a virtual machine; the REPL also exposes the VM’s memory view. The graph follows the sampled runtime code. The README’s optimization and GUI debugger items are planned, not implemented capabilities, so they are omitted.

Main entry points: [`source/Repl.cpp`](https://github.com/ruarq/br4in/blob/master/source/Repl.cpp) (Interactive REPL), [`source/VirtualMachine.cpp`](https://github.com/ruarq/br4in/blob/master/source/VirtualMachine.cpp) (Virtual machine), [`source/RunFile.cpp`](https://github.com/ruarq/br4in/blob/master/source/RunFile.cpp) (File runner), [`source/Parser.cpp`](https://github.com/ruarq/br4in/blob/master/source/Parser.cpp) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry modes"]
  node_main["CLI dispatch<br/>[Main.cpp]"]
  node_runfile["File runner<br/>[RunFile.cpp]"]
  node_repl["Interactive REPL<br/>[Repl.cpp]"]
end

subgraph group_frontend["Language frontend"]
  node_tokenizer["Tokenizer<br/>[Tokenizer.cpp]"]
  node_tokens["Token stream<br/>[Token.hpp]"]
  node_parser["Parser<br/>[Parser.cpp]"]
  node_ast["Parse tree<br/>[ParseTreeNodes.hpp]"]
end

subgraph group_execution["Compilation and execution"]
  node_compiler["Compiler<br/>[Compiler.cpp]"]
  node_chunk["Bytecode chunk<br/>[Chunk.cpp]"]
  node_vm["Virtual machine<br/>[VirtualMachine.cpp]"]
  node_memory["VM memory<br/>[VirtualMachine.hpp]"]
end

node_user(("User"))
node_sourcefile["Brainfuck file"]
node_terminal(("Console I/O"))

node_user -->|"select mode"| node_main
node_main -->|"runs file"| node_runfile
node_main -->|"starts REPL"| node_repl
node_user -->|"provides program"| node_sourcefile
node_sourcefile -->|"file contents"| node_runfile
node_runfile -->|"interprets source"| node_vm
node_user -->|"enters code"| node_repl
node_repl -->|"tokenizes input"| node_tokenizer
node_repl -->|"parses tokens"| node_parser
node_repl -->|"compiles tree"| node_compiler
node_repl -->|"interprets chunk"| node_vm
node_repl -->|"reads memory"| node_memory
node_tokenizer -->|"produces"| node_tokens
node_parser -->|"consumes"| node_tokens
node_parser -->|"builds"| node_ast
node_compiler -->|"visits"| node_ast
node_compiler -->|"writes bytecode"| node_chunk
node_vm -->|"tokenizes source"| node_tokenizer
node_vm -->|"parses tokens"| node_parser
node_vm -->|"compiles tree"| node_compiler
node_vm -->|"executes"| node_chunk
node_vm -->|"updates"| node_memory
node_vm -->|"reads and writes"| node_terminal
node_repl -->|"prompts and reports"| node_terminal
node_runfile -->|"reports errors"| node_terminal

click node_main "https://github.com/ruarq/br4in/blob/master/source/Main.cpp"
click node_runfile "https://github.com/ruarq/br4in/blob/master/source/RunFile.cpp"
click node_repl "https://github.com/ruarq/br4in/blob/master/source/Repl.cpp"
click node_tokenizer "https://github.com/ruarq/br4in/blob/master/source/Tokenizer.cpp"
click node_tokens "https://github.com/ruarq/br4in/blob/master/source/Token.hpp"
click node_parser "https://github.com/ruarq/br4in/blob/master/source/Parser.cpp"
click node_ast "https://github.com/ruarq/br4in/blob/master/source/ParseTreeNodes.hpp"
click node_compiler "https://github.com/ruarq/br4in/blob/master/source/Compiler.cpp"
click node_chunk "https://github.com/ruarq/br4in/blob/master/source/Chunk.cpp"
click node_vm "https://github.com/ruarq/br4in/blob/master/source/VirtualMachine.cpp"
click node_memory "https://github.com/ruarq/br4in/blob/master/source/VirtualMachine.hpp"

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_runfile,node_repl,node_user toneBlue
class node_tokenizer,node_tokens,node_parser,node_ast toneAmber
class node_compiler,node_chunk,node_vm,node_memory toneMint
class node_sourcefile,node_terminal toneIndigo
```

## Components

### Entry modes

- [CLI dispatch](https://github.com/ruarq/br4in/blob/master/source/Main.cpp): `source/Main.cpp`
- [File runner](https://github.com/ruarq/br4in/blob/master/source/RunFile.cpp): `source/RunFile.cpp`
- [Interactive REPL](https://github.com/ruarq/br4in/blob/master/source/Repl.cpp): `source/Repl.cpp`

### Language frontend

- [Tokenizer](https://github.com/ruarq/br4in/blob/master/source/Tokenizer.cpp): `source/Tokenizer.cpp`
- [Token stream](https://github.com/ruarq/br4in/blob/master/source/Token.hpp): `source/Token.hpp`
- [Parser](https://github.com/ruarq/br4in/blob/master/source/Parser.cpp): `source/Parser.cpp`
- [Parse tree](https://github.com/ruarq/br4in/blob/master/source/ParseTreeNodes.hpp): `source/ParseTreeNodes.hpp`

### Compilation and execution

- [Compiler](https://github.com/ruarq/br4in/blob/master/source/Compiler.cpp): `source/Compiler.cpp`
- [Bytecode chunk](https://github.com/ruarq/br4in/blob/master/source/Chunk.cpp): `source/Chunk.cpp`
- [Virtual machine](https://github.com/ruarq/br4in/blob/master/source/VirtualMachine.cpp): `source/VirtualMachine.cpp`
- [VM memory](https://github.com/ruarq/br4in/blob/master/source/VirtualMachine.hpp): `source/VirtualMachine.hpp`

### Other components

- **User**
- **Brainfuck file**
- **Console I/O**

## Connections

- User → CLI dispatch: select mode
- CLI dispatch → File runner: runs file
- CLI dispatch → Interactive REPL: starts REPL
- User → Brainfuck file: provides program
- Brainfuck file → File runner: file contents
- File runner → Virtual machine: interprets source
- User → Interactive REPL: enters code
- Interactive REPL → Tokenizer: tokenizes input
- Interactive REPL → Parser: parses tokens
- Interactive REPL → Compiler: compiles tree
- Interactive REPL → Virtual machine: interprets chunk
- Interactive REPL → VM memory: reads memory
- Tokenizer → Token stream: produces
- Parser → Token stream: consumes
- Parser → Parse tree: builds
- Compiler → Parse tree: visits
- Compiler → Bytecode chunk: writes bytecode
- Virtual machine → Tokenizer: tokenizes source
- Virtual machine → Parser: parses tokens
- Virtual machine → Compiler: compiles tree
- Virtual machine → Bytecode chunk: executes
- Virtual machine → VM memory: updates
- Virtual machine → Console I/O: reads and writes
- Interactive REPL → Console I/O: prompts and reports
- File runner → Console I/O: reports errors