# pku-minic/koopa architecture

> Architecture diagram of the GitHub repository pku-minic/koopa, 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/pku-minic/koopa
- Repository: https://github.com/pku-minic/koopa

## Overview

Koopa is a Rust library for parsing, building, optimizing, and emitting its strongly typed SSA intermediate representation; `libkoopa` exposes a C interface and raw-IR API. The main workflow is Koopa text input to an in-memory IR program, optional optimization, then Koopa or LLVM text output. The README also documents an optimizer, interpreter, and Brainfuck compiler as examples, not core library subsystems. Some implementation files were unsampled, so uncertain call relationships are omitted.

Main entry points: [`koopa/src/ir/entities.rs`](https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/entities.rs) (IR Program), [`koopa/src/front/driver.rs`](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/driver.rs) (Front Driver), [`koopa/src/front/builder.rs`](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/builder.rs) (IR Builder), [`koopa/src/opt/passman.rs`](https://github.com/pku-minic/koopa/blob/master/koopa/src/opt/passman.rs) (Pass Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Text Front End"]
  node_front_driver["Front Driver<br/>[driver.rs]"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_ast["Syntax Tree<br/>[ast.rs]"]
  node_front_builder["IR Builder<br/>[builder.rs]"]
end

subgraph group_ir["IR Core"]
  node_program[("IR Program<br/>[entities.rs]")]
  node_ir_builder["IR Construction<br/>[builder.rs]"]
  node_dataflow["Data Flow Graph<br/>[dfg.rs]"]
  node_layout["Block Layout<br/>[layout.rs]"]
end

subgraph group_optimization["Optimization"]
  node_pass_manager["Pass Manager<br/>[passman.rs]"]
  node_passes["Optimization Passes<br/>[pass.rs]"]
end

subgraph group_outputs["Generation And C API"]
  node_koopa_generator["Koopa Generator<br/>[koopa.rs]"]
  node_llvm_generator["LLVM Generator<br/>[llvm.rs]"]
  node_c_header["C API<br/>[koopa.h]"]
  node_c_driver["C Driver<br/>[driver.rs]"]
  node_raw_api["Raw IR API<br/>[mod.rs]"]
  node_raw_builder["Raw IR Builder<br/>[builder.rs]"]
  node_raw_generator["Raw IR Conversion<br/>[generator.rs]"]
end

node_compiler_user(("Compiler Client"))
node_koopa_text["Koopa IR Text"]
node_c_client(("C Client"))
node_llvm_text["LLVM IR Text"]
node_koopa_output["Koopa IR Output"]

node_compiler_user -->|"provides input"| node_koopa_text
node_koopa_text -->|"parsed by"| node_front_driver
node_front_driver -->|"tokenizes"| node_lexer
node_front_driver -->|"parses"| node_parser
node_parser -->|"produces syntax"| node_ast
node_front_driver -->|"builds IR"| node_front_builder
node_front_builder -->|"populates"| node_program
node_front_builder -->|"constructs values"| node_ir_builder
node_program -->|"organizes values"| node_dataflow
node_program -->|"organizes blocks"| node_layout
node_compiler_user -->|"may optimize"| node_pass_manager
node_pass_manager -->|"runs"| node_passes
node_pass_manager -->|"updates"| node_program
node_compiler_user -->|"requests output"| node_koopa_generator
node_koopa_generator -->|"reads"| node_program
node_koopa_generator -->|"emits"| node_koopa_output
node_compiler_user -->|"requests output"| node_llvm_generator
node_llvm_generator -->|"reads"| node_program
node_llvm_generator -->|"emits"| node_llvm_text
node_c_client -->|"calls"| node_c_header
node_c_header -->|"declares API"| node_c_driver
node_c_driver -->|"dispatches"| node_raw_api
node_raw_api -->|"builds raw view"| node_raw_builder
node_raw_generator -->|"generates from raw IR"| node_program
node_c_driver -->|"parses Koopa IR"| node_front_driver

click node_front_driver "https://github.com/pku-minic/koopa/blob/master/koopa/src/front/driver.rs"
click node_lexer "https://github.com/pku-minic/koopa/blob/master/koopa/src/front/lexer.rs"
click node_parser "https://github.com/pku-minic/koopa/blob/master/koopa/src/front/parser.rs"
click node_ast "https://github.com/pku-minic/koopa/blob/master/koopa/src/front/ast.rs"
click node_front_builder "https://github.com/pku-minic/koopa/blob/master/koopa/src/front/builder.rs"
click node_program "https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/entities.rs"
click node_ir_builder "https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/builder.rs"
click node_dataflow "https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/dfg.rs"
click node_layout "https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/layout.rs"
click node_pass_manager "https://github.com/pku-minic/koopa/blob/master/koopa/src/opt/passman.rs"
click node_passes "https://github.com/pku-minic/koopa/blob/master/koopa/src/opt/pass.rs"
click node_koopa_generator "https://github.com/pku-minic/koopa/blob/master/koopa/src/back/koopa.rs"
click node_llvm_generator "https://github.com/pku-minic/koopa/blob/master/koopa/src/back/llvm.rs"
click node_c_header "https://github.com/pku-minic/koopa/blob/master/libkoopa/include/koopa.h"
click node_c_driver "https://github.com/pku-minic/koopa/blob/master/libkoopa/src/driver.rs"
click node_raw_api "https://github.com/pku-minic/koopa/blob/master/libkoopa/src/raw/mod.rs"
click node_raw_builder "https://github.com/pku-minic/koopa/blob/master/libkoopa/src/raw/builder.rs"
click node_raw_generator "https://github.com/pku-minic/koopa/blob/master/libkoopa/src/raw/generator.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_front_driver,node_lexer,node_parser,node_ast,node_front_builder,node_compiler_user,node_c_client toneBlue
class node_program,node_ir_builder,node_dataflow,node_layout toneAmber
class node_pass_manager,node_passes toneMint
class node_koopa_generator,node_llvm_generator,node_c_header,node_c_driver,node_raw_api,node_raw_builder,node_raw_generator toneRose
class node_koopa_text,node_llvm_text,node_koopa_output toneIndigo
```

## Components

### Text Front End

- [Front Driver](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/driver.rs): `koopa/src/front/driver.rs`
- [Lexer](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/lexer.rs): `koopa/src/front/lexer.rs`
- [Parser](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/parser.rs): `koopa/src/front/parser.rs`
- [Syntax Tree](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/ast.rs): `koopa/src/front/ast.rs`
- [IR Builder](https://github.com/pku-minic/koopa/blob/master/koopa/src/front/builder.rs): `koopa/src/front/builder.rs`

### IR Core

- [IR Program](https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/entities.rs): `koopa/src/ir/entities.rs`
- [IR Construction](https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/builder.rs): `koopa/src/ir/builder.rs`
- [Data Flow Graph](https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/dfg.rs): `koopa/src/ir/dfg.rs`
- [Block Layout](https://github.com/pku-minic/koopa/blob/master/koopa/src/ir/layout.rs): `koopa/src/ir/layout.rs`

### Optimization

- [Pass Manager](https://github.com/pku-minic/koopa/blob/master/koopa/src/opt/passman.rs): `koopa/src/opt/passman.rs`
- [Optimization Passes](https://github.com/pku-minic/koopa/blob/master/koopa/src/opt/pass.rs): `koopa/src/opt/pass.rs`

### Generation And C API

- [Koopa Generator](https://github.com/pku-minic/koopa/blob/master/koopa/src/back/koopa.rs): `koopa/src/back/koopa.rs`
- [LLVM Generator](https://github.com/pku-minic/koopa/blob/master/koopa/src/back/llvm.rs): `koopa/src/back/llvm.rs`
- [C API](https://github.com/pku-minic/koopa/blob/master/libkoopa/include/koopa.h): `libkoopa/include/koopa.h`
- [C Driver](https://github.com/pku-minic/koopa/blob/master/libkoopa/src/driver.rs): `libkoopa/src/driver.rs`
- [Raw IR API](https://github.com/pku-minic/koopa/blob/master/libkoopa/src/raw/mod.rs): `libkoopa/src/raw/mod.rs`
- [Raw IR Builder](https://github.com/pku-minic/koopa/blob/master/libkoopa/src/raw/builder.rs): `libkoopa/src/raw/builder.rs`
- [Raw IR Conversion](https://github.com/pku-minic/koopa/blob/master/libkoopa/src/raw/generator.rs): `libkoopa/src/raw/generator.rs`

### Other components

- **Compiler Client**
- **Koopa IR Text**
- **C Client**
- **LLVM IR Text**
- **Koopa IR Output**

## Connections

- Compiler Client → Koopa IR Text: provides input
- Koopa IR Text → Front Driver: parsed by
- Front Driver → Lexer: tokenizes
- Front Driver → Parser: parses
- Parser → Syntax Tree: produces syntax
- Front Driver → IR Builder: builds IR
- IR Builder → IR Program: populates
- IR Builder → IR Construction: constructs values
- IR Program → Data Flow Graph: organizes values
- IR Program → Block Layout: organizes blocks
- Compiler Client → Pass Manager: may optimize
- Pass Manager → Optimization Passes: runs
- Pass Manager → IR Program: updates
- Compiler Client → Koopa Generator: requests output
- Koopa Generator → IR Program: reads
- Koopa Generator → Koopa IR Output: emits
- Compiler Client → LLVM Generator: requests output
- LLVM Generator → IR Program: reads
- LLVM Generator → LLVM IR Text: emits
- C Client → C API: calls
- C API → C Driver: declares API
- C Driver → Raw IR API: dispatches
- Raw IR API → Raw IR Builder: builds raw view
- Raw IR Conversion → IR Program: generates from raw IR
- C Driver → Front Driver: parses Koopa IR