# wuihee/toy-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/wuihee/toy-compiler
- Repository: https://github.com/wuihee/toy-compiler
- Video tour (about a minute): https://gitdiagram.com/wuihee/toy-compiler/video

## Overview

Toy Compiler is a MiniJava front end with two user-facing commands: scan reads a source file and prints tokens; parse reads a file, builds an AST, and prints it or a formatted parse error. The implemented stages are file/CLI dispatch, lexing, and parsing; type checking and later compiler stages are planned, not runtime components. Parser internals are sampled only partially, so the graph limits links to documented or directly evidenced interactions.

Main entry points: [`src/lib.rs`](https://github.com/wuihee/toy-compiler/blob/main/src/lib.rs) (File workflows), [`src/parser.rs`](https://github.com/wuihee/toy-compiler/blob/main/src/parser.rs) (MiniJava parser), [`src/lexer.rs`](https://github.com/wuihee/toy-compiler/blob/main/src/lexer.rs) (Lexer), [`src/main.rs`](https://github.com/wuihee/toy-compiler/blob/main/src/main.rs) (Command dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and file entry"]
  node_main["Command dispatch<br/>[main.rs]"]
  node_cli["Command definitions<br/>[cli.rs]"]
  node_library["File workflows<br/>[lib.rs]"]
end

subgraph group_lexing["Lexing"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_keywords["Keyword lookup<br/>[keywords.rs]"]
  node_tokens["Token definitions<br/>[token.rs]"]
end

subgraph group_parsing["Parsing and diagnostics"]
  node_parser["MiniJava parser<br/>[parser.rs]"]
  node_binding["Operator binding powers<br/>[binding_powers.rs]"]
  node_ast["AST model<br/>[ast.rs]"]
  node_errors["Parse error formatting<br/>[errors.rs]"]
  node_span["Source locations<br/>[span.rs]"]
end

node_user(("Compiler user"))
node_source["MiniJava source"]
node_terminal(("Terminal output"))

node_user -->|"runs command"| node_main
node_user -->|"provides file"| node_source
node_main -->|"parses arguments"| node_cli
node_main -->|"dispatches scan or parse"| node_library
node_library -->|"reads file"| node_source
node_library -->|"creates lexer"| node_lexer
node_library -->|"creates parser"| node_parser
node_lexer -->|"looks up words"| node_keywords
node_lexer -->|"produces tokens"| node_tokens
node_parser -->|"consumes tokens"| node_lexer
node_parser -->|"gets operator precedence"| node_binding
node_parser -->|"builds AST"| node_ast
node_parser -->|"returns parse errors"| node_errors
node_library -->|"formats parse errors"| node_errors
node_errors -->|"locates error"| node_span
node_lexer -->|"marks token positions"| node_span
node_library -->|"prints tokens, AST, or error"| node_terminal

click node_main "https://github.com/wuihee/toy-compiler/blob/main/src/main.rs"
click node_cli "https://github.com/wuihee/toy-compiler/blob/main/src/cli.rs"
click node_library "https://github.com/wuihee/toy-compiler/blob/main/src/lib.rs"
click node_lexer "https://github.com/wuihee/toy-compiler/blob/main/src/lexer.rs"
click node_keywords "https://github.com/wuihee/toy-compiler/blob/main/src/lexer/keywords.rs"
click node_tokens "https://github.com/wuihee/toy-compiler/blob/main/src/lexer/token.rs"
click node_parser "https://github.com/wuihee/toy-compiler/blob/main/src/parser.rs"
click node_binding "https://github.com/wuihee/toy-compiler/blob/main/src/parser/binding_powers.rs"
click node_ast "https://github.com/wuihee/toy-compiler/blob/main/src/ast.rs"
click node_errors "https://github.com/wuihee/toy-compiler/blob/main/src/parser/errors.rs"
click node_span "https://github.com/wuihee/toy-compiler/blob/main/src/span.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_main,node_cli,node_library,node_user toneBlue
class node_lexer,node_keywords,node_tokens toneAmber
class node_parser,node_binding,node_ast,node_errors,node_span toneMint
class node_source,node_terminal toneIndigo
```

## Components

### CLI and file entry

- [Command dispatch](https://github.com/wuihee/toy-compiler/blob/main/src/main.rs): `src/main.rs`
- [Command definitions](https://github.com/wuihee/toy-compiler/blob/main/src/cli.rs): `src/cli.rs`
- [File workflows](https://github.com/wuihee/toy-compiler/blob/main/src/lib.rs): `src/lib.rs`

### Lexing

- [Lexer](https://github.com/wuihee/toy-compiler/blob/main/src/lexer.rs): `src/lexer.rs`
- [Keyword lookup](https://github.com/wuihee/toy-compiler/blob/main/src/lexer/keywords.rs): `src/lexer/keywords.rs`
- [Token definitions](https://github.com/wuihee/toy-compiler/blob/main/src/lexer/token.rs): `src/lexer/token.rs`

### Parsing and diagnostics

- [MiniJava parser](https://github.com/wuihee/toy-compiler/blob/main/src/parser.rs): `src/parser.rs`
- [Operator binding powers](https://github.com/wuihee/toy-compiler/blob/main/src/parser/binding_powers.rs): `src/parser/binding_powers.rs`
- [AST model](https://github.com/wuihee/toy-compiler/blob/main/src/ast.rs): `src/ast.rs`
- [Parse error formatting](https://github.com/wuihee/toy-compiler/blob/main/src/parser/errors.rs): `src/parser/errors.rs`
- [Source locations](https://github.com/wuihee/toy-compiler/blob/main/src/span.rs): `src/span.rs`

### Other components

- **Compiler user**
- **MiniJava source**
- **Terminal output**

## Connections

- Compiler user → Command dispatch: runs command
- Compiler user → MiniJava source: provides file
- Command dispatch → Command definitions: parses arguments
- Command dispatch → File workflows: dispatches scan or parse
- File workflows → MiniJava source: reads file
- File workflows → Lexer: creates lexer
- File workflows → MiniJava parser: creates parser
- Lexer → Keyword lookup: looks up words
- Lexer → Token definitions: produces tokens
- MiniJava parser → Lexer: consumes tokens
- MiniJava parser → Operator binding powers: gets operator precedence
- MiniJava parser → AST model: builds AST
- MiniJava parser → Parse error formatting: returns parse errors
- File workflows → Parse error formatting: formats parse errors
- Parse error formatting → Source locations: locates error
- Lexer → Source locations: marks token positions
- File workflows → Terminal output: prints tokens, AST, or error