# o24s/stelaro architecture

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

- Interactive diagram: https://gitdiagram.com/o24s/stelaro
- Repository: https://github.com/o24s/stelaro

## Overview

Stelaro is a Rust implementation of a custom programming-language compiler; LLVM-based code generation is documented as work in progress. The principal workflow is source input through lexing, parsing, name resolution, AST-to-SIR lowering, and type checking, with diagnostics and shared compiler context supporting those stages. The interface and library expose compiler orchestration, but the excerpts do not establish every call in that orchestration. Code-generation details were not sampled, so that capability is shown only as a documented, unverified branch.

Main entry points: [`src/stelaro_sir/sir.rs`](https://github.com/o24s/stelaro/blob/master/src/stelaro_sir/sir.rs) (SIR Representation), [`src/stelaro_parse/parser.rs`](https://github.com/o24s/stelaro/blob/master/src/stelaro_parse/parser.rs) (Parser), [`src/stelaro_sir_typecheck/mod.rs`](https://github.com/o24s/stelaro/blob/master/src/stelaro_sir_typecheck/mod.rs) (Type Checker), [`src/lib.rs`](https://github.com/o24s/stelaro/blob/master/src/lib.rs) (Compiler Library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Source Front End"]
  node_library["Compiler Library<br/>[lib.rs]"]
  node_interface["Compiler Interface<br/>[interface.rs]"]
  node_passes["Compiler Passes<br/>[passes.rs]"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_tokens["Tokens and AST<br/>[ast.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
end

subgraph group_semantic["Semantic Analysis"]
  node_resolver["Name Resolver<br/>[mod.rs]"]
  node_lowering["AST Lowering<br/>[mod.rs]"]
  node_sir["SIR Representation<br/>[sir.rs]"]
  node_typecheck["Type Checker<br/>[mod.rs]"]
  node_types["Type System<br/>[ty.rs]"]
end

subgraph group_support["Compiler Infrastructure"]
  node_context["Compiler Context<br/>[mod.rs]"]
  node_session["Session and Options<br/>[config.rs]"]
  node_source["Source Map<br/>[source_map.rs]"]
  node_diagnostics["Diagnostics<br/>[diag.rs]"]
end

subgraph group_output["Compiler Output"]
  node_codegen["LLVM Code Generation"]
end

node_user(("Compiler User"))

node_user -.->|"invokes compiler"| node_library
node_library -->|"exposes"| node_interface
node_library -->|"exposes"| node_passes
node_passes -->|"uses parsing"| node_parser
node_parser -->|"creates lexer"| node_lexer
node_lexer -->|"produces tokens"| node_tokens
node_parser -->|"builds AST"| node_tokens
node_passes -->|"uses context"| node_context
node_lowering -->|"builds SIR"| node_sir
node_resolver -->|"records resolutions"| node_sir
node_typecheck -->|"checks SIR"| node_sir
node_typecheck -->|"infers types"| node_types
node_context -->|"stores SIR"| node_sir
node_context -->|"holds session"| node_session
node_session -->|"configures source map"| node_source
node_lexer -->|"emits errors"| node_diagnostics
node_parser -->|"reports parse errors"| node_diagnostics
node_typecheck -->|"reports errors"| node_diagnostics
node_sir -.->|"feeds code generation"| node_codegen

click node_library "https://github.com/o24s/stelaro/blob/master/src/lib.rs"
click node_interface "https://github.com/o24s/stelaro/blob/master/src/stelaro_interface/interface.rs"
click node_passes "https://github.com/o24s/stelaro/blob/master/src/stelaro_interface/passes.rs"
click node_lexer "https://github.com/o24s/stelaro/blob/master/src/stelaro_lexer/lexer.rs"
click node_tokens "https://github.com/o24s/stelaro/blob/master/src/stelaro_ast/ast.rs"
click node_parser "https://github.com/o24s/stelaro/blob/master/src/stelaro_parse/parser.rs"
click node_resolver "https://github.com/o24s/stelaro/blob/master/src/stelaro_resolve/mod.rs"
click node_lowering "https://github.com/o24s/stelaro/blob/master/src/stelaro_ast_lowering/mod.rs"
click node_sir "https://github.com/o24s/stelaro/blob/master/src/stelaro_sir/sir.rs"
click node_typecheck "https://github.com/o24s/stelaro/blob/master/src/stelaro_sir_typecheck/mod.rs"
click node_types "https://github.com/o24s/stelaro/blob/master/src/stelaro_ty/ty.rs"
click node_context "https://github.com/o24s/stelaro/blob/master/src/stelaro_context/mod.rs"
click node_session "https://github.com/o24s/stelaro/blob/master/src/stelaro_session/config.rs"
click node_source "https://github.com/o24s/stelaro/blob/master/src/stelaro_common/source_map.rs"
click node_diagnostics "https://github.com/o24s/stelaro/blob/master/src/stelaro_diagnostics/diag.rs"
click node_codegen "https://github.com/o24s/stelaro/tree/master/src/stelaro_codegen"

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_library,node_interface,node_passes,node_lexer,node_tokens,node_parser,node_user toneBlue
class node_resolver,node_lowering,node_sir,node_typecheck,node_types toneAmber
class node_context,node_session,node_source,node_diagnostics toneMint
class node_codegen toneRose
```

## Components

### Source Front End

- [Compiler Library](https://github.com/o24s/stelaro/blob/master/src/lib.rs): `src/lib.rs`
- [Compiler Interface](https://github.com/o24s/stelaro/blob/master/src/stelaro_interface/interface.rs): `src/stelaro_interface/interface.rs`
- [Compiler Passes](https://github.com/o24s/stelaro/blob/master/src/stelaro_interface/passes.rs): `src/stelaro_interface/passes.rs`
- [Lexer](https://github.com/o24s/stelaro/blob/master/src/stelaro_lexer/lexer.rs): `src/stelaro_lexer/lexer.rs`
- [Tokens and AST](https://github.com/o24s/stelaro/blob/master/src/stelaro_ast/ast.rs): `src/stelaro_ast/ast.rs`
- [Parser](https://github.com/o24s/stelaro/blob/master/src/stelaro_parse/parser.rs): `src/stelaro_parse/parser.rs`

### Semantic Analysis

- [Name Resolver](https://github.com/o24s/stelaro/blob/master/src/stelaro_resolve/mod.rs): `src/stelaro_resolve/mod.rs`
- [AST Lowering](https://github.com/o24s/stelaro/blob/master/src/stelaro_ast_lowering/mod.rs): `src/stelaro_ast_lowering/mod.rs`
- [SIR Representation](https://github.com/o24s/stelaro/blob/master/src/stelaro_sir/sir.rs): `src/stelaro_sir/sir.rs`
- [Type Checker](https://github.com/o24s/stelaro/blob/master/src/stelaro_sir_typecheck/mod.rs): `src/stelaro_sir_typecheck/mod.rs`
- [Type System](https://github.com/o24s/stelaro/blob/master/src/stelaro_ty/ty.rs): `src/stelaro_ty/ty.rs`

### Compiler Infrastructure

- [Compiler Context](https://github.com/o24s/stelaro/blob/master/src/stelaro_context/mod.rs): `src/stelaro_context/mod.rs`
- [Session and Options](https://github.com/o24s/stelaro/blob/master/src/stelaro_session/config.rs): `src/stelaro_session/config.rs`
- [Source Map](https://github.com/o24s/stelaro/blob/master/src/stelaro_common/source_map.rs): `src/stelaro_common/source_map.rs`
- [Diagnostics](https://github.com/o24s/stelaro/blob/master/src/stelaro_diagnostics/diag.rs): `src/stelaro_diagnostics/diag.rs`

### Compiler Output

- [LLVM Code Generation](https://github.com/o24s/stelaro/tree/master/src/stelaro_codegen): `src/stelaro_codegen`

### Other components

- **Compiler User**

## Connections

- Compiler User → Compiler Library: invokes compiler
- Compiler Library → Compiler Interface: exposes (evidence: `src/lib.rs`)
- Compiler Library → Compiler Passes: exposes (evidence: `src/lib.rs`)
- Compiler Passes → Parser: uses parsing (evidence: `src/stelaro_interface/passes.rs`)
- Parser → Lexer: creates lexer
- Lexer → Tokens and AST: produces tokens (evidence: `src/stelaro_lexer/lexer.rs`)
- Parser → Tokens and AST: builds AST (evidence: `src/stelaro_parse/parser.rs`)
- Compiler Passes → Compiler Context: uses context (evidence: `src/stelaro_interface/passes.rs`)
- AST Lowering → SIR Representation: builds SIR (evidence: `src/stelaro_ast_lowering/mod.rs`)
- Name Resolver → SIR Representation: records resolutions (evidence: `src/stelaro_resolve/mod.rs`)
- Type Checker → SIR Representation: checks SIR (evidence: `src/stelaro_sir_typecheck/mod.rs`)
- Type Checker → Type System: infers types (evidence: `src/stelaro_sir_typecheck/mod.rs`)
- Compiler Context → SIR Representation: stores SIR (evidence: `src/stelaro_context/mod.rs`)
- Compiler Context → Session and Options: holds session (evidence: `src/stelaro_context/mod.rs`)
- Session and Options → Source Map: configures source map (evidence: `src/stelaro_session/session.rs`)
- Lexer → Diagnostics: emits errors (evidence: `src/stelaro_lexer/lexer.rs`)
- Parser → Diagnostics: reports parse errors
- Type Checker → Diagnostics: reports errors (evidence: `src/stelaro_sir_typecheck/mod.rs`)
- SIR Representation → LLVM Code Generation: feeds code generation
