# peeperlanguage/compiler architecture

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

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

## Overview

#### Purpose and Entry Points
Peeper is a Go-implemented compiler toolchain for the Peeper programming language, with package/project management and Language Server Protocol support. The primary executable starts at `cmd/main.go`; command dispatch and compiler-facing commands are in `cmd/dispatch.go`, `cmd/build.go`, and `cmd/command.go`. The compiler façade is `internal/driver/compiler.go`.

#### CLI, Projects, and Dependencies
The CLI handles build plus project lifecycle and dependency operations (`init`, `get`, `update`, `remove`, scanning/listing orphaned dependencies). Project manifests and lockfiles are modeled in `pkg/manifest/manifest.go` and `pkg/manifest/lockfile.go`. Dependency resolution/download boundaries are represented by `pkg/remotes/remotes.go`, `pkg/registry/download.go`, and `pkg/registry/cache.go`.

Project loading establishes module/import context before compilation: `internal/project/context.go`, `internal/project/modules.go`, and `internal/project/imports.go`. This layer separates filesystem/project topology from language analysis.

#### Frontend: Source to AST
Compilation begins by loading source files through the pipeline, lexing Peeper syntax, and parsing surface declarations/expressions into the AST. Core stages are `internal/pipeline/loader.go`, `internal/frontend/lexer/lexer.go`, and `internal/frontend/parser/parser.go`. The shared syntax model—including declarations, expressions, statements, metadata, and source locations—is in `internal/frontend/ast/decl.go`, `internal/frontend/ast/expr.go`, and `internal/frontend/ast/stmt.go`.

#### Semantic Analysis and Safety
Semantic passes build symbol/scope information, resolve names/types, validate control flow, and enforce Peeper’s ownership/reference rules. Key boundaries are collection/binding (`internal/semantics/collector/collector.go`, `internal/semantics/binder/binder.go`), resolution and typing (`internal/semantics/resolver/resolver.go`, `internal/semantics/typechecker/typechecker.go`), and ownership/place analysis (`internal/semantics/ownership/ownership.go`, `internal/semantics/place/origin.go`). CFG analysis supports flow-sensitive validation in `internal/semantics/cfg/build.go` and `internal/semantics/cfg/analyze.go`.

Diagnostics are accumulated and rendered independently of the compiler stages via `internal/diagnostics/bag.go`, `internal/diagnostics/diagnostic.go`, and `internal/diagnostics/emitter.go`.

#### IR Lowering and Code Generation
Validated AST is lowered through explicit intermediate representations: high-level IR in `internal/ir/hir/model.go`, HIR lowering in `internal/ir/hir_lower/lower.go`, then machine-oriented IR in `internal/ir/mir/model.go` and `internal/ir/mir/lower.go`. Constant folding spans this boundary in `internal/ir/constfold.go`.

The backend abstraction is `internal/backend/backend.go`; its concrete LLVM implementation lowers IR, types, calls, drops, and modules through `internal/backend/llvm/lower_llvm.go`, `internal/backend/llvm/type_lowering.go`, and `internal/backend/llvm/module_emit.go`. LLVM and target triples are material external/runtime dependencies, represented by `internal/target/llvm_triple.go`.

#### Runtime and Built-ins
Language-provided core functionality is compiled from Peeper source under `_builtin_library/core/src`, notably allocation and globals in `_builtin_library/core/src/allocator.peep` and `_builtin_library/core/src/global.peep`. Prelude integration is centralized in `internal/prelude/prelude.go`. This forms the boundary between user projects and compiler-supplied runtime/library code.

#### Language Server
The LSP server shares compiler/project concepts while maintaining workspace state for editor requests. Its JSON-RPC server boundary is `internal/lsp/server.go` and `internal/lsp/jsonrpc.go`; incremental document/workspace state lives in `internal/lsp/state.go` and `internal/lsp/workspace.go`. Editor features such as completion, hover, and navigation are implemented in `internal/lsp/completion.go`, `internal/lsp/hover.go`, and `internal/lsp/navigation.go`.

Main entry points: [`internal/project/context.go`](https://github.com/peeperlanguage/compiler/blob/main/internal/project/context.go) (Project context), [`cmd/dispatch.go`](https://github.com/peeperlanguage/compiler/blob/main/cmd/dispatch.go) (Command dispatch), [`internal/driver/compiler.go`](https://github.com/peeperlanguage/compiler/blob/main/internal/driver/compiler.go) (Compiler driver), [`internal/semantics/binder/binder.go`](https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/binder/binder.go) (Symbols & binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & Projects"]
  node_entry["Peeper executable<br/>Go entry point<br/>[main.go]"]
  node_commands["Command dispatch<br/>CLI commands<br/>[dispatch.go]"]
  node_compiler["Compiler driver<br/>compiler façade<br/>[compiler.go]"]
  node_manifest["Manifest &amp; lockfile<br/>project metadata<br/>[manifest.go]"]
  node_dependencies[("Dependency services<br/>registry and cache<br/>[remotes.go]")]
  node_project["Project context<br/>module importer<br/>[context.go]"]
end

subgraph group_frontend["Frontend &amp; Semantics"]
  node_loader["Source loader<br/>pipeline stage<br/>[loader.go]"]
  node_lexer["Lexer<br/>frontend stage<br/>[lexer.go]"]
  node_parser["Parser<br/>frontend stage<br/>[parser.go]"]
  node_ast["Syntax AST<br/>language model<br/>[decl.go]"]
  node_binding["Symbols &amp; binding<br/>semantic pass<br/>[binder.go]"]
  node_typing["Resolution &amp; typing<br/>semantic pass<br/>[typechecker.go]"]
  node_safety["Flow &amp; ownership<br/>semantic validation<br/>[ownership.go]"]
  node_diagnostics["Diagnostics<br/>error reporting<br/>[bag.go]"]
end

subgraph group_lowering["IR &amp; Backend"]
  node_hir["High-level IR<br/>intermediate representation<br/>[model.go]"]
  node_mir["Machine IR<br/>intermediate representation<br/>[lower.go]"]
  node_backend["LLVM backend<br/>code generator<br/>[lower_llvm.go]"]
  node_target{{"LLVM target<br/>external toolchain<br/>[llvm_triple.go]"}}
  node_prelude["Prelude &amp; core runtime<br/>built-in library<br/>[prelude.go]"]
end

subgraph group_language["Language Server"]
  node_lsp_server["LSP JSON-RPC server<br/>editor protocol<br/>[server.go]"]
  node_lsp_state[("Workspace state<br/>incremental documents<br/>[state.go]")]
  node_lsp_features["Editor features<br/>completion and navigation<br/>[completion.go]"]
end

node_entry --> node_commands
node_commands -->|"build"| node_compiler
node_commands -->|"project commands"| node_manifest
node_commands -->|"dependency commands"| node_dependencies
node_manifest -->|"module metadata"| node_project
node_dependencies -->|"resolved packages"| node_project
node_compiler -->|"loads project"| node_project
node_compiler -->|"compiles sources"| node_loader
node_project -->|"source/module context"| node_loader
node_loader --> node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"builds"| node_ast
node_ast --> node_binding
node_binding -->|"symbols"| node_typing
node_typing -->|"typed AST"| node_safety
node_binding -.->|"reports"| node_diagnostics
node_typing -.->|"reports"| node_diagnostics
node_safety -.->|"reports"| node_diagnostics
node_safety -->|"validated AST"| node_hir
node_hir -->|"lowering"| node_mir
node_mir -->|"code generation"| node_backend
node_backend -->|"uses LLVM"| node_target
node_prelude -->|"built-in imports"| node_project
node_lsp_server -->|"document updates"| node_lsp_state
node_lsp_state -->|"workspace model"| node_lsp_features
node_lsp_features -.->|"shared analysis"| node_compiler
node_lsp_state -.->|"workspace projects"| node_project

click node_entry "https://github.com/peeperlanguage/compiler/blob/main/cmd/main.go"
click node_commands "https://github.com/peeperlanguage/compiler/blob/main/cmd/dispatch.go"
click node_compiler "https://github.com/peeperlanguage/compiler/blob/main/internal/driver/compiler.go"
click node_manifest "https://github.com/peeperlanguage/compiler/blob/main/pkg/manifest/manifest.go"
click node_dependencies "https://github.com/peeperlanguage/compiler/blob/main/pkg/remotes/remotes.go"
click node_project "https://github.com/peeperlanguage/compiler/blob/main/internal/project/context.go"
click node_loader "https://github.com/peeperlanguage/compiler/blob/main/internal/pipeline/loader.go"
click node_lexer "https://github.com/peeperlanguage/compiler/blob/main/internal/frontend/lexer/lexer.go"
click node_parser "https://github.com/peeperlanguage/compiler/blob/main/internal/frontend/parser/parser.go"
click node_ast "https://github.com/peeperlanguage/compiler/blob/main/internal/frontend/ast/decl.go"
click node_binding "https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/binder/binder.go"
click node_typing "https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/typechecker/typechecker.go"
click node_safety "https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/ownership/ownership.go"
click node_diagnostics "https://github.com/peeperlanguage/compiler/blob/main/internal/diagnostics/bag.go"
click node_hir "https://github.com/peeperlanguage/compiler/blob/main/internal/ir/hir/model.go"
click node_mir "https://github.com/peeperlanguage/compiler/blob/main/internal/ir/mir/lower.go"
click node_backend "https://github.com/peeperlanguage/compiler/blob/main/internal/backend/llvm/lower_llvm.go"
click node_target "https://github.com/peeperlanguage/compiler/blob/main/internal/target/llvm_triple.go"
click node_prelude "https://github.com/peeperlanguage/compiler/blob/main/internal/prelude/prelude.go"
click node_lsp_server "https://github.com/peeperlanguage/compiler/blob/main/internal/lsp/server.go"
click node_lsp_state "https://github.com/peeperlanguage/compiler/blob/main/internal/lsp/state.go"
click node_lsp_features "https://github.com/peeperlanguage/compiler/blob/main/internal/lsp/completion.go"

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_entry,node_commands,node_compiler,node_manifest,node_dependencies,node_project toneBlue
class node_loader,node_lexer,node_parser,node_ast,node_binding,node_typing,node_safety,node_diagnostics toneAmber
class node_hir,node_mir,node_backend,node_target,node_prelude toneMint
class node_lsp_server,node_lsp_state,node_lsp_features toneRose
```

## Components

### CLI & Projects

- [Peeper executable](https://github.com/peeperlanguage/compiler/blob/main/cmd/main.go): Go entry point · `cmd/main.go`
- [Command dispatch](https://github.com/peeperlanguage/compiler/blob/main/cmd/dispatch.go): CLI commands · Build and project lifecycle commands. · `cmd/dispatch.go`
- [Compiler driver](https://github.com/peeperlanguage/compiler/blob/main/internal/driver/compiler.go): compiler façade · `internal/driver/compiler.go`
- [Manifest & lockfile](https://github.com/peeperlanguage/compiler/blob/main/pkg/manifest/manifest.go): project metadata · `pkg/manifest/manifest.go`
- [Dependency services](https://github.com/peeperlanguage/compiler/blob/main/pkg/remotes/remotes.go): registry and cache · Resolves, downloads, and caches packages. · `pkg/remotes/remotes.go`
- [Project context](https://github.com/peeperlanguage/compiler/blob/main/internal/project/context.go): module importer · Establishes module topology and imports. · `internal/project/context.go`

### Frontend & Semantics

- [Source loader](https://github.com/peeperlanguage/compiler/blob/main/internal/pipeline/loader.go): pipeline stage · `internal/pipeline/loader.go`
- [Lexer](https://github.com/peeperlanguage/compiler/blob/main/internal/frontend/lexer/lexer.go): frontend stage · `internal/frontend/lexer/lexer.go`
- [Parser](https://github.com/peeperlanguage/compiler/blob/main/internal/frontend/parser/parser.go): frontend stage · `internal/frontend/parser/parser.go`
- [Syntax AST](https://github.com/peeperlanguage/compiler/blob/main/internal/frontend/ast/decl.go): language model · Declarations, expressions, statements, and locations. · `internal/frontend/ast/decl.go`
- [Symbols & binding](https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/binder/binder.go): semantic pass · `internal/semantics/binder/binder.go`
- [Resolution & typing](https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/typechecker/typechecker.go): semantic pass · `internal/semantics/typechecker/typechecker.go`
- [Flow & ownership](https://github.com/peeperlanguage/compiler/blob/main/internal/semantics/ownership/ownership.go): semantic validation · CFG, ownership, and place analysis. · `internal/semantics/ownership/ownership.go`
- [Diagnostics](https://github.com/peeperlanguage/compiler/blob/main/internal/diagnostics/bag.go): error reporting · Collects and renders compiler diagnostics. · `internal/diagnostics/bag.go`

### IR & Backend

- [High-level IR](https://github.com/peeperlanguage/compiler/blob/main/internal/ir/hir/model.go): intermediate representation · `internal/ir/hir/model.go`
- [Machine IR](https://github.com/peeperlanguage/compiler/blob/main/internal/ir/mir/lower.go): intermediate representation · Includes MIR lowering and constant folding boundary. · `internal/ir/mir/lower.go`
- [LLVM backend](https://github.com/peeperlanguage/compiler/blob/main/internal/backend/llvm/lower_llvm.go): code generator · Lowers IR and emits LLVM modules. · `internal/backend/llvm/lower_llvm.go`
- [LLVM target](https://github.com/peeperlanguage/compiler/blob/main/internal/target/llvm_triple.go): external toolchain · LLVM and target triple integration. · `internal/target/llvm_triple.go`
- [Prelude & core runtime](https://github.com/peeperlanguage/compiler/blob/main/internal/prelude/prelude.go): built-in library · Compiler-provided Peeper core code. · `internal/prelude/prelude.go`

### Language Server

- [LSP JSON-RPC server](https://github.com/peeperlanguage/compiler/blob/main/internal/lsp/server.go): editor protocol · `internal/lsp/server.go`
- [Workspace state](https://github.com/peeperlanguage/compiler/blob/main/internal/lsp/state.go): incremental documents · `internal/lsp/state.go`
- [Editor features](https://github.com/peeperlanguage/compiler/blob/main/internal/lsp/completion.go): completion and navigation · `internal/lsp/completion.go`

## Connections

- Peeper executable → Command dispatch
- Command dispatch → Compiler driver: build
- Command dispatch → Manifest & lockfile: project commands
- Command dispatch → Dependency services: dependency commands
- Manifest & lockfile → Project context: module metadata
- Dependency services → Project context: resolved packages
- Compiler driver → Project context: loads project
- Compiler driver → Source loader: compiles sources
- Project context → Source loader: source/module context
- Source loader → Lexer
- Lexer → Parser: tokens
- Parser → Syntax AST: builds
- Syntax AST → Symbols & binding
- Symbols & binding → Resolution & typing: symbols
- Resolution & typing → Flow & ownership: typed AST
- Symbols & binding → Diagnostics: reports
- Resolution & typing → Diagnostics: reports
- Flow & ownership → Diagnostics: reports
- Flow & ownership → High-level IR: validated AST
- High-level IR → Machine IR: lowering
- Machine IR → LLVM backend: code generation
- LLVM backend → LLVM target: uses LLVM
- Prelude & core runtime → Project context: built-in imports
- LSP JSON-RPC server → Workspace state: document updates
- Workspace state → Editor features: workspace model
- Editor features → Compiler driver: shared analysis
- Workspace state → Project context: workspace projects