# kkorel/wacc-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/kkorel/wacc-compiler
- Repository: https://github.com/kkorel/wacc-compiler

## Overview

WACC-Compiler is a command-line compiler: a user supplies a WACC file, which is parsed, scope-renamed, type-checked, translated through two intermediate representations, formatted as x86-64 assembly, and written as a .s file. The README also documents language features including arrays, pairs, functions, I/O and runtime safety checks; these are represented at their compiler stages. Some subsystem links reflect the documented pipeline because their implementations were not sampled.

Main entry points: [`src/main/wacc/Main.scala`](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/Main.scala) (CLI driver), [`src/main/wacc/parser.scala`](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/parser.scala) (Parser), [`src/main/wacc/renamer.scala`](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/renamer.scala) (Scope renamer), [`src/main/wacc/backend/stackMachine.scala`](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/stackMachine.scala) (Stack IR lowering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Frontend"]
  node_main["CLI driver<br/>[Main.scala]"]
  node_lexer["Lexer<br/>[lexer.scala]"]
  node_parser["Parser<br/>[parser.scala]"]
  node_ast["Program AST<br/>[ast.scala]"]
  node_errors["Diagnostics<br/>[errors.scala]"]
end

subgraph group_semantics["Semantic Analysis"]
  node_renamer["Scope renamer<br/>[renamer.scala]"]
  node_checker["Type checker<br/>[typeChecker.scala]"]
end

subgraph group_codegen["Code Generation"]
  node_stackmachine["Stack IR lowering<br/>[stackMachine.scala]"]
  node_stackir["Stack IR<br/>[stackCode.scala]"]
  node_x86lowerer["x86 lowering<br/>[x86Lowerer.scala]"]
  node_x86ir["x86 IR<br/>[x86IR.scala]"]
end

subgraph group_output["Output"]
  node_formatter["Assembly formatter<br/>[x86Formatter.scala]"]
end

node_user(("Compiler user"))
node_input["WACC source"]
node_assembly["Assembly file"]
node_gcc["GNU assembler and linker"]
node_runtime["Generated program"]
node_libc["Linux libc"]

node_user -->|"provides source"| node_input
node_user -->|"invokes"| node_main
node_main -->|"reads file"| node_input
node_main -->|"parses via"| node_parser
node_parser -->|"tokenizes with"| node_lexer
node_parser -->|"produces AST"| node_ast
node_main -->|"formats failures"| node_errors
node_main -->|"resolves names"| node_renamer
node_renamer -->|"returns renamed AST"| node_checker
node_main -->|"checks types"| node_checker
node_main -->|"lowers typed AST"| node_stackmachine
node_stackmachine -->|"emits instructions"| node_stackir
node_main -->|"lowers stack IR"| node_x86lowerer
node_x86lowerer -->|"emits instructions"| node_x86ir
node_main -->|"formats x86 IR"| node_formatter
node_formatter -->|"writes assembly"| node_assembly
node_user -.->|"assembles output"| node_gcc
node_gcc -.->|"builds executable"| node_runtime
node_runtime -.->|"calls routines"| node_libc

click node_main "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/Main.scala"
click node_lexer "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/lexer.scala"
click node_parser "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/parser.scala"
click node_ast "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/ast.scala"
click node_errors "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/errors.scala"
click node_renamer "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/renamer.scala"
click node_checker "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/typeChecker.scala"
click node_stackmachine "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/stackMachine.scala"
click node_stackir "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/stackCode.scala"
click node_x86lowerer "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/x86Lowerer.scala"
click node_x86ir "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/x86IR.scala"
click node_formatter "https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/x86Formatter.scala"

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_lexer,node_parser,node_ast,node_errors,node_user toneBlue
class node_renamer,node_checker toneAmber
class node_stackmachine,node_stackir,node_x86lowerer,node_x86ir toneMint
class node_formatter toneRose
class node_input,node_assembly,node_gcc,node_runtime,node_libc toneIndigo
```

## Components

### Frontend

- [CLI driver](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/Main.scala): `src/main/wacc/Main.scala`
- [Lexer](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/lexer.scala): `src/main/wacc/lexer.scala`
- [Parser](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/parser.scala): `src/main/wacc/parser.scala`
- [Program AST](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/ast.scala): `src/main/wacc/ast.scala`
- [Diagnostics](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/errors.scala): `src/main/wacc/errors.scala`

### Semantic Analysis

- [Scope renamer](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/renamer.scala): `src/main/wacc/renamer.scala`
- [Type checker](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/typeChecker.scala): `src/main/wacc/typeChecker.scala`

### Code Generation

- [Stack IR lowering](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/stackMachine.scala): `src/main/wacc/backend/stackMachine.scala`
- [Stack IR](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/stackCode.scala): `src/main/wacc/backend/stackCode.scala`
- [x86 lowering](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/x86Lowerer.scala): `src/main/wacc/backend/x86Lowerer.scala`
- [x86 IR](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/x86IR.scala): `src/main/wacc/backend/x86IR.scala`

### Output

- [Assembly formatter](https://github.com/kkorel/wacc-compiler/blob/main/src/main/wacc/backend/x86Formatter.scala): `src/main/wacc/backend/x86Formatter.scala`

### Other components

- **Compiler user**
- **WACC source**
- **Assembly file**
- **GNU assembler and linker**
- **Generated program**
- **Linux libc**

## Connections

- Compiler user → WACC source: provides source
- Compiler user → CLI driver: invokes
- CLI driver → WACC source: reads file
- CLI driver → Parser: parses via
- Parser → Lexer: tokenizes with
- Parser → Program AST: produces AST
- CLI driver → Diagnostics: formats failures
- CLI driver → Scope renamer: resolves names
- Scope renamer → Type checker: returns renamed AST
- CLI driver → Type checker: checks types
- CLI driver → Stack IR lowering: lowers typed AST
- Stack IR lowering → Stack IR: emits instructions
- CLI driver → x86 lowering: lowers stack IR
- x86 lowering → x86 IR: emits instructions
- CLI driver → Assembly formatter: formats x86 IR
- Assembly formatter → Assembly file: writes assembly
- Compiler user → GNU assembler and linker: assembles output
- GNU assembler and linker → Generated program: builds executable
- Generated program → Linux libc: calls routines