# berylang/compiler architecture

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

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

## Overview

1. **What this repository is**
   Bery is a compiler for a custom `.bry` language. The codebase is organized as a classic front end → semantic analysis → LLVM-based back end pipeline, with `src/main.cpp` acting as the entry point that likely wires the phases together.

2. **Overall compilation flow**
   Source files are first tokenized by the lexer, then parsed into an AST, then semantically validated, and finally lowered into LLVM IR and optimized before native code generation. The README explicitly describes this as a custom C++ frontend with an LLVM backend.

3. **Lexing layer**
   `src/lexer/` contains the tokenizer (`lexer.cpp/.h`) and token definitions (`token.h`). This layer is the first boundary from raw text into compiler-internal structure, producing tokens consumed by the parser.

4. **Parsing and AST construction**
   `src/parser/` implements a recursive-descent parser (`parser.cpp/.h`) and a tree of AST node types under `src/parser/ast/`. The AST is split by language construct: literals, expressions, functions, control flow, variable declarations, arrays, imports, and blocks/program nodes. This layer owns syntactic structure, but not type correctness.

5. **Semantic analysis**
   `src/sema/` is the validation layer. It includes a `symboltable` for scope and identifier management, a `typechecker` for static typing and compatibility rules, and a `sema` coordinator that walks the AST. This phase appears responsible for scope resolution, type checking, and implicit casts as described in the README.

6. **Import handling**
   `src/importer/` is a distinct subsystem for module/import support. It includes an `importer` and a `mangler`, which suggests imported symbols are resolved and names are adjusted to avoid collisions or encode module identity before later compilation stages.

7. **Code generation architecture**
   `src/codegen/` translates the validated AST into LLVM IR. There is a higher-level `codegen.cpp/.h` facade plus `src/codegen/irgen/` split by concern: `declarations.cpp`, `expressions.cpp`, and `controlflow.cpp`. That layout indicates lowering is organized by AST category rather than by output file.

8. **LLVM integration and optimization**
   `src/codegen/llvm/` contains the LLVM-facing implementation (`irgen.cpp/.h`) and an `optimizer` module. This is the boundary where Bery’s internal IR generation becomes actual LLVM IR, and then optimization passes are likely applied before emitting machine code or object output.

9. **Language surface represented in examples**
   The `examples/` directory is a good map of supported language features. It includes arrays, components, control flow, datatypes, expressions, functions, and imports, which implies the compiler already covers a fairly broad statically typed language core: variables, conditionals, loops, function calls, casting, strings, and module usage.

10. **Build and project structure**
   `CMakeLists.txt` indicates a CMake-based native build, consistent with a C++ compiler project. The repository is structured as a single compiler executable with modular subsystems rather than multiple services or runtime components.

11. **Important architectural boundary**
   The most important separation is between syntax and semantics: parser code builds the AST without enforcing type rules, while `sema` validates and annotates that AST before code generation. That boundary is critical for any diagram because codegen depends on semantic correctness, not raw parse trees.

12. **How to diagram the system**
   A clear architecture diagram should show: `.bry` source files entering the lexer, tokens flowing to the parser, AST flowing into semantic analysis, validated AST feeding the code generator, then LLVM IR passing through optimization and onward to native output. Supporting boxes should sit beside the main path for imports, symbol table/type checking, and AST node definitions.

Main entry points: [`src/sema/sema.cpp`](https://github.com/berylang/compiler/blob/main/src/sema/sema.cpp) (Sema), [`src/codegen/irgen`](https://github.com/berylang/compiler/tree/main/src/codegen/irgen) (IR Gen), [`src/codegen/llvm/irgen.cpp`](https://github.com/berylang/compiler/blob/main/src/codegen/llvm/irgen.cpp) (LLVM IR), [`src/parser/parser.cpp`](https://github.com/berylang/compiler/blob/main/src/parser/parser.cpp) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Compiler pipeline"]
  node_main["Main<br/>entrypoint<br/>[main.cpp]"]
end

subgraph group_frontend["Front end"]
  node_lexer["Lexer<br/>tokenizer<br/>[lexer.cpp]"]
  node_token["Token<br/>[token.h]"]
  node_parser["Parser<br/>recursive-descent<br/>[parser.cpp]"]
  node_ast{{"AST<br/>syntax tree"}}
end

subgraph group_analysis["Semantic analysis"]
  node_sema["Sema<br/>[sema.cpp]"]
  node_symboltable[("Symbols<br/>scope table<br/>[symboltable.cpp]")]
  node_typechecker["Types<br/>type checker<br/>[typechecker.cpp]"]
  node_importer["Importer<br/>module resolver<br/>[importer.cpp]"]
  node_mangler["Mangler<br/>[mangler.cpp]"]
end

subgraph group_backend["Back end"]
  node_codegen["Codegen<br/>lowering facade<br/>[codegen.cpp]"]
  node_irgen["IR Gen<br/>AST lowering"]
  node_decls["Decls<br/>lowering stage<br/>[declarations.cpp]"]
  node_exprs["Exprs<br/>lowering stage<br/>[expressions.cpp]"]
  node_flow["Flow<br/>lowering stage<br/>[controlflow.cpp]"]
  node_llvmir["LLVM IR<br/>llvm backend<br/>[irgen.cpp]"]
  node_opt["Optimizer<br/>llvm passes<br/>[optimizer.cpp]"]
end

subgraph group_support["Supporting assets"]
  node_examples["Examples<br/>language samples"]
  node_build["Build<br/>[CMakeLists.txt]"]
end

node_main -->|"starts"| node_lexer
node_lexer -->|"emits"| node_token
node_token -->|"feeds"| node_parser
node_parser -->|"builds"| node_ast
node_ast -->|"analyzed by"| node_sema
node_sema -->|"uses"| node_symboltable
node_sema -->|"uses"| node_typechecker
node_sema -->|"resolves"| node_importer
node_importer -->|"names"| node_mangler
node_sema -->|"validates for"| node_codegen
node_codegen -->|"delegates"| node_irgen
node_irgen -->|"lowers"| node_decls
node_irgen -->|"lowers"| node_exprs
node_irgen -->|"lowers"| node_flow
node_decls -->|"produces"| node_llvmir
node_exprs -->|"produces"| node_llvmir
node_flow -->|"produces"| node_llvmir
node_llvmir -->|"optimizes"| node_opt
node_examples -.->|"exercises"| node_parser
node_build -.->|"builds"| node_main

click node_main "https://github.com/berylang/compiler/blob/main/src/main.cpp"
click node_lexer "https://github.com/berylang/compiler/blob/main/src/lexer/lexer.cpp"
click node_token "https://github.com/berylang/compiler/blob/main/src/lexer/token.h"
click node_parser "https://github.com/berylang/compiler/blob/main/src/parser/parser.cpp"
click node_ast "https://github.com/berylang/compiler/tree/main/src/parser/ast"
click node_sema "https://github.com/berylang/compiler/blob/main/src/sema/sema.cpp"
click node_symboltable "https://github.com/berylang/compiler/blob/main/src/sema/symboltable.cpp"
click node_typechecker "https://github.com/berylang/compiler/blob/main/src/sema/typechecker.cpp"
click node_importer "https://github.com/berylang/compiler/blob/main/src/importer/importer.cpp"
click node_mangler "https://github.com/berylang/compiler/blob/main/src/importer/mangler.cpp"
click node_codegen "https://github.com/berylang/compiler/blob/main/src/codegen/codegen.cpp"
click node_irgen "https://github.com/berylang/compiler/tree/main/src/codegen/irgen"
click node_decls "https://github.com/berylang/compiler/blob/main/src/codegen/irgen/declarations.cpp"
click node_exprs "https://github.com/berylang/compiler/blob/main/src/codegen/irgen/expressions.cpp"
click node_flow "https://github.com/berylang/compiler/blob/main/src/codegen/irgen/controlflow.cpp"
click node_llvmir "https://github.com/berylang/compiler/blob/main/src/codegen/llvm/irgen.cpp"
click node_opt "https://github.com/berylang/compiler/blob/main/src/codegen/llvm/optimizer.cpp"
click node_examples "https://github.com/berylang/compiler/tree/main/examples"
click node_build "https://github.com/berylang/compiler/blob/main/CMakeLists.txt"

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 toneBlue
class node_lexer,node_token,node_parser,node_ast toneAmber
class node_sema,node_symboltable,node_typechecker,node_importer,node_mangler toneMint
class node_codegen,node_irgen,node_decls,node_exprs,node_flow,node_llvmir,node_opt toneRose
class node_examples,node_build toneIndigo
```

## Components

### Compiler pipeline

Main source-to-native compilation flow.

- [Main](https://github.com/berylang/compiler/blob/main/src/main.cpp): entrypoint · Wires compiler phases together. · `src/main.cpp`

### Front end

Lexing, parsing, and AST construction.

- [Lexer](https://github.com/berylang/compiler/blob/main/src/lexer/lexer.cpp): tokenizer · Converts source text into tokens. · `src/lexer/lexer.cpp`
- [Token](https://github.com/berylang/compiler/blob/main/src/lexer/token.h): token model · Token definitions shared with the parser. · `src/lexer/token.h`
- [Parser](https://github.com/berylang/compiler/blob/main/src/parser/parser.cpp): recursive-descent · Builds the AST from token streams. · `src/parser/parser.cpp`
- [AST](https://github.com/berylang/compiler/tree/main/src/parser/ast): syntax tree · Language node hierarchy for literals, expressions, functions, control flow, variables, arrays, imports, and programs. · `src/parser/ast`

### Semantic analysis

Scope, types, and import resolution.

- [Sema](https://github.com/berylang/compiler/blob/main/src/sema/sema.cpp): semantic pass · Coordinates scope and type validation over the AST. · `src/sema/sema.cpp`
- [Symbols](https://github.com/berylang/compiler/blob/main/src/sema/symboltable.cpp): scope table · Tracks identifiers and lexical scopes. · `src/sema/symboltable.cpp`
- [Types](https://github.com/berylang/compiler/blob/main/src/sema/typechecker.cpp): type checker · Enforces static typing and compatibility rules. · `src/sema/typechecker.cpp`
- [Importer](https://github.com/berylang/compiler/blob/main/src/importer/importer.cpp): module resolver · Handles module/import resolution before later compilation stages. · `src/importer/importer.cpp`
- [Mangler](https://github.com/berylang/compiler/blob/main/src/importer/mangler.cpp): name mangler · Encodes imported or scoped names to avoid collisions. · `src/importer/mangler.cpp`

### Back end

LLVM IR generation and optimization.

- [Codegen](https://github.com/berylang/compiler/blob/main/src/codegen/codegen.cpp): lowering facade · Top-level AST-to-LLVM lowering entrypoint. · `src/codegen/codegen.cpp`
- [IR Gen](https://github.com/berylang/compiler/tree/main/src/codegen/irgen): AST lowering · Dispatches lowering by AST category. · `src/codegen/irgen`
- [Decls](https://github.com/berylang/compiler/blob/main/src/codegen/irgen/declarations.cpp): lowering stage · Lowers declarations and variable-related constructs. · `src/codegen/irgen/declarations.cpp`
- [Exprs](https://github.com/berylang/compiler/blob/main/src/codegen/irgen/expressions.cpp): lowering stage · Lowers expressions into IR. · `src/codegen/irgen/expressions.cpp`
- [Flow](https://github.com/berylang/compiler/blob/main/src/codegen/irgen/controlflow.cpp): lowering stage · Lowers control-flow constructs into IR. · `src/codegen/irgen/controlflow.cpp`
- [LLVM IR](https://github.com/berylang/compiler/blob/main/src/codegen/llvm/irgen.cpp): llvm backend · Translates internal lowering into LLVM IR. · `src/codegen/llvm/irgen.cpp`
- [Optimizer](https://github.com/berylang/compiler/blob/main/src/codegen/llvm/optimizer.cpp): llvm passes · Applies LLVM optimizations before output. · `src/codegen/llvm/optimizer.cpp`

### Supporting assets

Examples and build entrypoints.

- [Examples](https://github.com/berylang/compiler/tree/main/examples): language samples · Feature-oriented .bry programs covering arrays, control flow, datatypes, expressions, functions, components, and imports. · `examples`
- [Build](https://github.com/berylang/compiler/blob/main/CMakeLists.txt): cmake build · Native CMake build entrypoint for the compiler executable. · `CMakeLists.txt`

## Connections

- Main → Lexer: starts · Compiler begins by tokenizing source.
- Lexer → Token: emits · Tokenizer produces token objects.
- Token → Parser: feeds · Parser consumes token streams.
- Parser → AST: builds · Parser constructs the AST hierarchy.
- AST → Sema: analyzed by · Semantic analysis walks the parsed tree.
- Sema → Symbols: uses · Scope and identifier tracking support sema.
- Sema → Types: uses · Type rules are enforced during semantic analysis.
- Sema → Importer: resolves · Imports are handled as part of semantic/module processing.
- Importer → Mangler: names · Imported symbols are mangled for uniqueness.
- Sema → Codegen: validates for · Only semantically valid AST reaches code generation.
- Codegen → IR Gen: delegates · Facade routes lowering to IR generation.
- IR Gen → Decls: lowers · Declaration-related constructs are lowered separately.
- IR Gen → Exprs: lowers · Expression lowering is isolated.
- IR Gen → Flow: lowers · Control flow lowering is isolated.
- Decls → LLVM IR: produces · Lowered constructs become LLVM IR.
- Exprs → LLVM IR: produces · Expression lowering feeds LLVM IR generation.
- Flow → LLVM IR: produces · Control-flow lowering feeds LLVM IR generation.
- LLVM IR → Optimizer: optimizes · LLVM IR is optimized before final emission.
- Examples → Parser: exercises · Example programs cover supported syntax and semantics.
- Build → Main: builds · CMake builds the compiler executable.