# hydra-language/hydra architecture

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

- Interactive diagram: https://gitdiagram.com/hydra-language/hydra
- Repository: https://github.com/hydra-language/hydra

## Overview

#### Purpose and Workspace
Hydra is a Rust workspace implementing a statically typed, data-oriented systems language and its `hydrac` compiler. It compiles Hydra source through an LLVM-based backend and can build multi-file programs such as the raytracer example. Workspace structure is rooted at `Cargo.toml`; language syntax is defined in `grammar.md`.

#### Compiler Entry and Source Environment
The command-line compiler starts in `cli/src/main.rs`. It owns compilation invocation and source/sysroot discovery, with `cli/src/sysroot.rs` locating bundled language libraries. The compiler consumes user `.hydra` modules plus standard-library source under `stdlib/core/primitives.hydra`, `stdlib/core/intrinsics.hydra`, and allocation APIs in `stdlib/alloc/boxed.hydra`.

#### Front End: Lexing, Parsing, Modules
Lexical input becomes tokens in `crates/lexer/src/lexer.rs` and `crates/lexer/src/token.rs`. The parser converts tokens into the AST in `crates/parser/src/parser.rs` and `crates/parser/src/ast.rs`; module loading/import structure is handled by `crates/parser/src/module.rs`. This is the boundary from source text to compiler-owned syntax structures.

#### Semantic Analysis and Typed IR
`crates/analyzer/src/analyzer.rs` coordinates name resolution, scopes, typing, expression/statement analysis, and generic specialization. Core stages include `crates/analyzer/src/resolve.rs`, `crates/analyzer/src/types.rs`, and `crates/analyzer/src/monomorphizer.rs`. Analysis lowers or populates the shared IR model in `crates/ir/src/hir.rs`, with expressions, statements, types, and compiler context represented in `crates/ir/src/expr.rs`, `crates/ir/src/stmt.rs`, and `crates/ir/src/context.rs`.

#### Safety and Mid-Level Processing
Borrow validation is a dedicated phase in `crates/borrowcheck/src/borrowcheck.rs`, operating after semantic structure is available and before final emission. A separate MIR layer provides construction and optimization: `crates/mir/src/builder.rs` and `crates/mir/src/optimizer.rs`. These layers form the main correctness/optimization boundary between typed language semantics and backend-oriented code generation.

#### LLVM Code Generation
The backend is implemented by `crates/codegen/src/lib.rs`, translating IR/MIR concepts to LLVM. It has specialized lowering for functions, expressions, statements, types, and compiler intrinsics/builtins in `crates/codegen/src/functions.rs`, `crates/codegen/src/expressions.rs`, and `crates/codegen/src/builtins.rs`. LLVM and Clang are material external dependencies: LLVM 14 is explicitly required on Windows, while Clang is required on Linux for the native toolchain.

#### Runtime and Native Startup
Generated programs link against a Rust runtime in `runtime/src/lib.rs`, including allocator support in `runtime/src/alloc.rs`. Architecture-specific startup assembly establishes the process entry boundary at `runtime/arch/x86_64/start.s` and `runtime/arch/aarch_64/start.s`. This separates language-level code generation from platform ABI/process initialization.

#### Diagnostics and Representative Programs
Cross-cutting compiler diagnostics are centralized in `crates/errors/src/error.rs`. `examples/hello/hello.hydra` is a minimal compile target; `examples/raytracing/main.hydra` and its companion modules demonstrate supported structs, methods, pointers/references, casts, and complex control flow. Linux is the reliable target for the raytracer; the README notes a Windows stack bug.

Main entry points: [`crates/analyzer/src/analyzer.rs`](https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/analyzer.rs) (Semantic analyzer), [`crates/parser/src/parser.rs`](https://github.com/hydra-language/hydra/blob/master/crates/parser/src/parser.rs) (Parser), [`crates/codegen/src/lib.rs`](https://github.com/hydra-language/hydra/blob/master/crates/codegen/src/lib.rs) (LLVM codegen), [`cli/src/main.rs`](https://github.com/hydra-language/hydra/blob/master/cli/src/main.rs) (hydrac CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Language inputs"]
  node_cli["hydrac CLI<br/>compiler entry<br/>[main.rs]"]
  node_sysroot["Sysroot discovery<br/>source locator<br/>[sysroot.rs]"]
  node_user_source["Hydra programs<br/>source modules<br/>[main.hydra]"]
  node_stdlib["Standard library<br/>Hydra sources<br/>[primitives.hydra]"]
end

subgraph group_frontend["Front end"]
  node_lexer["Lexer<br/>tokenization<br/>[lexer.rs]"]
  node_tokens["Tokens<br/>syntax model<br/>[token.rs]"]
  node_parser["Parser<br/>AST construction<br/>[parser.rs]"]
  node_ast["AST<br/>syntax tree<br/>[ast.rs]"]
  node_modules["Module loader<br/>imports<br/>[module.rs]"]
end

subgraph group_semantics["Semantic pipeline"]
  node_analyzer["Semantic analyzer<br/>typing and resolution<br/>[analyzer.rs]"]
  node_resolution_types["Resolution and types<br/>semantic rules<br/>[resolve.rs]"]
  node_monomorphizer["Monomorphizer<br/>generic specialization<br/>[monomorphizer.rs]"]
  node_hir["Typed HIR<br/>shared IR<br/>[hir.rs]"]
  node_borrowcheck["Borrow checker<br/>safety validation<br/>[borrowcheck.rs]"]
  node_mir["MIR builder and optimizer<br/>mid-level IR<br/>[builder.rs]"]
end

subgraph group_backend["Native backend"]
  node_codegen["LLVM codegen<br/>backend lowering<br/>[lib.rs]"]
  node_llvm{{"LLVM and Clang<br/>native toolchain"}}
  node_native_program["Native executable<br/>compiler output"]
end

subgraph group_runtime["Runtime"]
  node_runtime["Rust runtime<br/>runtime library<br/>[lib.rs]"]
  node_startup["Architecture startup<br/>process entry<br/>[start.s]"]
end

node_diagnostics["Diagnostics<br/>error reporting<br/>[error.rs]"]

node_cli -->|"discovers"| node_sysroot
node_sysroot -->|"locates"| node_stdlib
node_cli -->|"compiles"| node_user_source
node_user_source -->|"source text"| node_lexer
node_stdlib -->|"library source"| node_lexer
node_lexer -->|"produces"| node_tokens
node_tokens -->|"consumed by"| node_parser
node_parser -->|"builds"| node_ast
node_parser -->|"loads imports"| node_modules
node_ast -->|"analyzes"| node_analyzer
node_modules -->|"module structure"| node_analyzer
node_analyzer -->|"uses"| node_resolution_types
node_analyzer -->|"specializes"| node_monomorphizer
node_analyzer -->|"populates"| node_hir
node_hir -->|"validates"| node_borrowcheck
node_borrowcheck -->|"safe typed structure"| node_mir
node_mir -->|"optimized IR"| node_codegen
node_codegen -->|"emits through"| node_llvm
node_codegen -->|"links"| node_runtime
node_startup -->|"establishes entry"| node_native_program
node_llvm -->|"builds"| node_native_program
node_runtime -->|"linked into"| node_native_program
node_diagnostics -.->|"reports through"| node_cli
node_diagnostics -.->|"reports errors"| node_analyzer

click node_cli "https://github.com/hydra-language/hydra/blob/master/cli/src/main.rs"
click node_sysroot "https://github.com/hydra-language/hydra/blob/master/cli/src/sysroot.rs"
click node_user_source "https://github.com/hydra-language/hydra/blob/master/examples/raytracing/main.hydra"
click node_stdlib "https://github.com/hydra-language/hydra/blob/master/stdlib/core/primitives.hydra"
click node_lexer "https://github.com/hydra-language/hydra/blob/master/crates/lexer/src/lexer.rs"
click node_tokens "https://github.com/hydra-language/hydra/blob/master/crates/lexer/src/token.rs"
click node_parser "https://github.com/hydra-language/hydra/blob/master/crates/parser/src/parser.rs"
click node_ast "https://github.com/hydra-language/hydra/blob/master/crates/parser/src/ast.rs"
click node_modules "https://github.com/hydra-language/hydra/blob/master/crates/parser/src/module.rs"
click node_analyzer "https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/analyzer.rs"
click node_resolution_types "https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/resolve.rs"
click node_monomorphizer "https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/monomorphizer.rs"
click node_hir "https://github.com/hydra-language/hydra/blob/master/crates/ir/src/hir.rs"
click node_borrowcheck "https://github.com/hydra-language/hydra/blob/master/crates/borrowcheck/src/borrowcheck.rs"
click node_mir "https://github.com/hydra-language/hydra/blob/master/crates/mir/src/builder.rs"
click node_codegen "https://github.com/hydra-language/hydra/blob/master/crates/codegen/src/lib.rs"
click node_runtime "https://github.com/hydra-language/hydra/blob/master/runtime/src/lib.rs"
click node_startup "https://github.com/hydra-language/hydra/blob/master/runtime/arch/x86_64/start.s"
click node_diagnostics "https://github.com/hydra-language/hydra/blob/master/crates/errors/src/error.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_cli,node_sysroot,node_user_source,node_stdlib toneBlue
class node_lexer,node_tokens,node_parser,node_ast,node_modules toneAmber
class node_analyzer,node_resolution_types,node_monomorphizer,node_hir,node_borrowcheck,node_mir toneMint
class node_codegen,node_llvm,node_native_program toneRose
class node_runtime,node_startup toneIndigo
class node_diagnostics toneNeutral
```

## Components

### Language inputs

- [hydrac CLI](https://github.com/hydra-language/hydra/blob/master/cli/src/main.rs): compiler entry · Owns compilation invocation and source/sysroot discovery. · `cli/src/main.rs`
- [Sysroot discovery](https://github.com/hydra-language/hydra/blob/master/cli/src/sysroot.rs): source locator · `cli/src/sysroot.rs`
- [Hydra programs](https://github.com/hydra-language/hydra/blob/master/examples/raytracing/main.hydra): source modules · Includes single- and multi-file user programs. · `examples/raytracing/main.hydra`
- [Standard library](https://github.com/hydra-language/hydra/blob/master/stdlib/core/primitives.hydra): Hydra sources · Core primitives, intrinsics, and allocation APIs. · `stdlib/core/primitives.hydra`

### Front end

- [Lexer](https://github.com/hydra-language/hydra/blob/master/crates/lexer/src/lexer.rs): tokenization · `crates/lexer/src/lexer.rs`
- [Tokens](https://github.com/hydra-language/hydra/blob/master/crates/lexer/src/token.rs): syntax model · `crates/lexer/src/token.rs`
- [Parser](https://github.com/hydra-language/hydra/blob/master/crates/parser/src/parser.rs): AST construction · `crates/parser/src/parser.rs`
- [AST](https://github.com/hydra-language/hydra/blob/master/crates/parser/src/ast.rs): syntax tree · `crates/parser/src/ast.rs`
- [Module loader](https://github.com/hydra-language/hydra/blob/master/crates/parser/src/module.rs): imports · `crates/parser/src/module.rs`

### Semantic pipeline

- [Semantic analyzer](https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/analyzer.rs): typing and resolution · Coordinates scopes, expression analysis, and generic specialization. · `crates/analyzer/src/analyzer.rs`
- [Resolution and types](https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/resolve.rs): semantic rules · `crates/analyzer/src/resolve.rs`
- [Monomorphizer](https://github.com/hydra-language/hydra/blob/master/crates/analyzer/src/monomorphizer.rs): generic specialization · `crates/analyzer/src/monomorphizer.rs`
- [Typed HIR](https://github.com/hydra-language/hydra/blob/master/crates/ir/src/hir.rs): shared IR · Shared expressions, statements, types, and compiler context. · `crates/ir/src/hir.rs`
- [Borrow checker](https://github.com/hydra-language/hydra/blob/master/crates/borrowcheck/src/borrowcheck.rs): safety validation · `crates/borrowcheck/src/borrowcheck.rs`
- [MIR builder and optimizer](https://github.com/hydra-language/hydra/blob/master/crates/mir/src/builder.rs): mid-level IR · Builds and optimizes backend-oriented representation. · `crates/mir/src/builder.rs`

### Native backend

- [LLVM codegen](https://github.com/hydra-language/hydra/blob/master/crates/codegen/src/lib.rs): backend lowering · Lowers functions, expressions, statements, types, and builtins. · `crates/codegen/src/lib.rs`
- **LLVM and Clang**: native toolchain · External LLVM backend and native toolchain dependencies.
- **Native executable**: compiler output

### Runtime

- [Rust runtime](https://github.com/hydra-language/hydra/blob/master/runtime/src/lib.rs): runtime library · Provides allocator support for generated programs. · `runtime/src/lib.rs`
- [Architecture startup](https://github.com/hydra-language/hydra/blob/master/runtime/arch/x86_64/start.s): process entry · Assembly establishes the platform ABI entry boundary. · `runtime/arch/x86_64/start.s`

### Other components

- [Diagnostics](https://github.com/hydra-language/hydra/blob/master/crates/errors/src/error.rs): error reporting · Cross-cutting compiler error reporting. · `crates/errors/src/error.rs`

## Connections

- hydrac CLI → Sysroot discovery: discovers
- Sysroot discovery → Standard library: locates
- hydrac CLI → Hydra programs: compiles
- Hydra programs → Lexer: source text
- Standard library → Lexer: library source
- Lexer → Tokens: produces
- Tokens → Parser: consumed by
- Parser → AST: builds
- Parser → Module loader: loads imports
- AST → Semantic analyzer: analyzes
- Module loader → Semantic analyzer: module structure
- Semantic analyzer → Resolution and types: uses
- Semantic analyzer → Monomorphizer: specializes
- Semantic analyzer → Typed HIR: populates
- Typed HIR → Borrow checker: validates
- Borrow checker → MIR builder and optimizer: safe typed structure
- MIR builder and optimizer → LLVM codegen: optimized IR
- LLVM codegen → LLVM and Clang: emits through
- LLVM codegen → Rust runtime: links
- Architecture startup → Native executable: establishes entry
- LLVM and Clang → Native executable: builds
- Rust runtime → Native executable: linked into
- Diagnostics → hydrac CLI: reports through
- Diagnostics → Semantic analyzer: reports errors