# houssameddine-yousfi/justcompiler architecture

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

- Interactive diagram: https://gitdiagram.com/houssameddine-yousfi/justcompiler
- Repository: https://github.com/houssameddine-yousfi/justcompiler

## Overview

1. **What this repository is**
   - This is not a traditional code-generating compiler yet; it is an **interpreted language implementation** for the “Just” JVM language.
   - The architecture is a classic compiler front end plus evaluator: **source text → tokens → syntax tree → bound tree → execution result**.

2. **Top-level orchestration**
   - `Compilation`, `SyntaxTree`, `Evaluator`, `EvaluationResult`, and `Index` form the main execution path.
   - The driver/REPL behavior described in the README appears to be coordinated at the top level, likely through `Index`, which feeds user input into the compilation pipeline and prints either results or diagnostics.

3. **Text and source management**
   - The `Text` package (`SourceText`, `TextLine`, `TextSpan`) models the original input and exact source locations.
   - This layer exists primarily to support **accurate diagnostics**, including line/column spans and highlighted error messages.

4. **Lexical analysis**
   - `Syntax/Lexer` converts raw source text into `SyntaxToken` objects.
   - `SyntaxKind` and `SyntaxFacts` define the language vocabulary: keywords, operators, punctuation, literals, and precedence/associativity rules.
   - This layer is responsible for turning malformed text into recoverable lexer diagnostics rather than failing outright.

5. **Parsing and syntax tree**
   - `Syntax/Parser` builds the concrete syntax tree rooted at `CompilationUnitSyntax`.
   - The syntax layer includes expression and statement nodes for:
     - literals, names, unary/binary expressions, parenthesized expressions
     - assignments and variable declarations
     - blocks, `if/else`, `while`, and `for`
   - `SyntaxNode`, `ExpressionSyntax`, `StatementSyntax`, and the specific syntax classes define the tree structure used before semantic analysis.

6. **Semantic binding**
   - The `Binding` package lowers syntax into a typed, semantically valid bound tree.
   - `Binder` resolves names, checks operator applicability, enforces scope rules, and converts syntax into `Bound*` nodes.
   - `BoundScope`, `BoundGlobalScope`, and `VariableSymbol` model declaration visibility, read-only variables, and shadowing/redeclaration rules.
   - `BoundBinaryOperator`, `BoundUnaryOperator`, and their `Kind` enums encode the supported operator/type combinations.

7. **Runtime evaluation**
   - `Evaluator` executes the bound tree and produces the final value for an expression or statement block.
   - Bound node types such as `BoundBlockStatement`, `BoundIfStatment`, `BoundWhileStatement`, `BoundForStatement`, `BoundVariableDeclaration`, and `BoundAssignmentExpression` represent the executable form.
   - The language is currently **value-oriented**: the result of a block is the last expression/value produced.

8. **Diagnostics as a first-class subsystem**
   - `Diagnostic` and `DiagnosticsBag` accumulate errors across lexing, parsing, binding, and evaluation phases.
   - This is a key boundary in the architecture: syntax errors, type errors, undefined variables, and scope violations are all reported through the same diagnostic channel.
   - The README’s highlighted error spans are enabled by the `Text` layer plus these diagnostic classes.

9. **Language model and supported semantics**
   - The repo supports **integers and booleans** only.
   - Operators include arithmetic, equality/inequality, comparison, and logical negation.
   - Control flow includes `if/else`, `while`, `for`, and block scoping.
   - Variables can be declared mutable (`var`) or read-only (`const`), with scoping preventing invalid redeclarations or out-of-scope access.

10. **Testing structure**
   - Tests are split by subsystem, which mirrors the architecture:
     - `Syntax/LexerTest`, `Syntax/ParserTest`, `Syntax/SyntaxFactsTest`
     - `EvaluationTest`
     - `Text/SourceTextTest`
   - This indicates the repo is organized around validating each compiler phase independently, which is useful when drawing the architecture diagram.

11. **Build/runtime environment**
   - The project is built with **Maven** and targets **Java 17+**.
   - There are no external services or infrastructure dependencies; the system is self-contained and runs entirely on the JVM.

12. **Best diagram boundary**
   - A clear architecture diagram should show four main layers:
     - **Input/Text handling**
     - **Syntax processing**
     - **Binding/semantic analysis**
     - **Evaluation/runtime**
   - Diagnostics should be drawn as a cross-cutting concern spanning all layers.

Main entry points: [`src/main/java/com/JsonAjax/justcompiler/Binding/Binder.java`](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/Binder.java) (Binder), [`src/main/java/com/JsonAjax/justcompiler/Compilation.java`](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Compilation.java) (Compilation), [`src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxTree.java`](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxTree.java) (Syntax Tree), [`src/main/java/com/JsonAjax/justcompiler/Syntax/Lexer.java`](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/Lexer.java) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Orchestration"]
  node_index["Index<br/>repl/driver<br/>[Index.java]"]
  node_compilation["Compilation<br/>pipeline<br/>[Compilation.java]"]
  node_diagnostics[("Diagnostics<br/>error bag")]
  node_diagnostic["Diagnostic<br/>error entry<br/>[Diagnostic.java]"]
end

subgraph group_text["Text"]
  node_source_text["Source Text<br/>text model<br/>[SourceText.java]"]
  node_text_span["Text Span<br/>span model<br/>[TextSpan.java]"]
  node_text_line["Text Line<br/>line model<br/>[TextLine.java]"]
end

subgraph group_syntax["Syntax"]
  node_syntax_tree["Syntax Tree<br/>parse facade<br/>[SyntaxTree.java]"]
  node_lexer["Lexer<br/>tokenizer<br/>[Lexer.java]"]
  node_parser["Parser<br/>[Parser.java]"]
  node_syntax_facts["Syntax Facts<br/>language rules<br/>[SyntaxFacts.java]"]
  node_syntax_nodes["Syntax Nodes<br/>ast model<br/>[SyntaxNode.java]"]
end

subgraph group_binding["Binding"]
  node_binder["Binder<br/>semantic analyzer<br/>[Binder.java]"]
  node_bound_scope["Bound Scope<br/>scope model<br/>[BoundScope.java]"]
  node_global_scope["Global Scope<br/>scope snapshot"]
  node_variable_symbol["Variable Symbol"]
  node_bound_ops["Bound Ops<br/>operator tables"]
  node_bound_nodes["Bound Nodes<br/>bound tree<br/>[BoundNode.java]"]
end

subgraph group_runtime["Runtime"]
  node_evaluator["Evaluator<br/>runtime executor<br/>[Evaluator.java]"]
  node_evaluation_result["Eval Result<br/>result wrapper"]
end

node_index -->|"runs"| node_compilation
node_compilation -->|"parses"| node_syntax_tree
node_syntax_tree -->|"uses"| node_lexer
node_syntax_tree -->|"uses"| node_parser
node_lexer -->|"reads"| node_source_text
node_lexer -->|"consults"| node_syntax_facts
node_parser -->|"builds"| node_syntax_nodes
node_parser -->|"consults"| node_syntax_facts
node_source_text -->|"maps"| node_text_line
node_source_text -->|"supports"| node_text_span
node_syntax_tree -->|"reports"| node_diagnostics
node_lexer -->|"reports"| node_diagnostics
node_parser -->|"reports"| node_diagnostics
node_compilation -->|"binds"| node_binder
node_binder -->|"uses"| node_bound_scope
node_binder -->|"produces"| node_global_scope
node_binder -->|"declares"| node_variable_symbol
node_binder -->|"matches"| node_bound_ops
node_binder -->|"creates"| node_bound_nodes
node_bound_scope -->|"contains"| node_variable_symbol
node_compilation -->|"executes"| node_evaluator
node_evaluator -->|"walks"| node_bound_nodes
node_evaluator -->|"returns"| node_evaluation_result
node_evaluator -->|"reports"| node_diagnostics
node_evaluation_result -->|"contains"| node_diagnostic

click node_index "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Index.java"
click node_compilation "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Compilation.java"
click node_syntax_tree "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxTree.java"
click node_lexer "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/Lexer.java"
click node_parser "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/Parser.java"
click node_syntax_facts "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxFacts.java"
click node_syntax_nodes "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxNode.java"
click node_source_text "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Text/SourceText.java"
click node_text_span "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Text/TextSpan.java"
click node_text_line "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Text/TextLine.java"
click node_diagnostics "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/DiagnosticsBag.java"
click node_diagnostic "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Diagnostic.java"
click node_binder "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/Binder.java"
click node_bound_scope "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundScope.java"
click node_global_scope "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundGlobalScope.java"
click node_variable_symbol "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/VariableSymbol.java"
click node_bound_ops "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundBinaryOperator.java"
click node_bound_nodes "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundNode.java"
click node_evaluator "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Evaluator.java"
click node_evaluation_result "https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/EvaluationResult.java"

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_index,node_compilation,node_diagnostics,node_diagnostic toneBlue
class node_source_text,node_text_span,node_text_line toneAmber
class node_syntax_tree,node_lexer,node_parser,node_syntax_facts,node_syntax_nodes toneMint
class node_binder,node_bound_scope,node_global_scope,node_variable_symbol,node_bound_ops,node_bound_nodes toneRose
class node_evaluator,node_evaluation_result toneIndigo
```

## Components

### Orchestration

Entry point and compilation flow.

- [Index](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Index.java): repl/driver · Interactive entry point that accepts input and prints results or diagnostics. · `src/main/java/com/JsonAjax/justcompiler/Index.java`
- [Compilation](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Compilation.java): pipeline · Coordinates syntax analysis, binding, and evaluation for a submission. · `src/main/java/com/JsonAjax/justcompiler/Compilation.java`
- [Diagnostics](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/DiagnosticsBag.java): error bag · Collects errors across lexing, parsing, binding, and evaluation. · `src/main/java/com/JsonAjax/justcompiler/DiagnosticsBag.java`
- [Diagnostic](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Diagnostic.java): error entry · Represents a single reported problem with source context. · `src/main/java/com/JsonAjax/justcompiler/Diagnostic.java`

### Text

Source text and location tracking.

- [Source Text](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Text/SourceText.java): text model · Stores source input with line and span mapping for diagnostics. · `src/main/java/com/JsonAjax/justcompiler/Text/SourceText.java`
- [Text Span](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Text/TextSpan.java): span model · Represents highlighted source ranges used in error reporting. · `src/main/java/com/JsonAjax/justcompiler/Text/TextSpan.java`
- [Text Line](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Text/TextLine.java): line model · Tracks line boundaries and offsets in the original source. · `src/main/java/com/JsonAjax/justcompiler/Text/TextLine.java`

### Syntax

Lexing, parsing, and concrete syntax tree.

- [Syntax Tree](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxTree.java): parse facade · Wraps parsing into a tree usable by later phases. · `src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxTree.java`
- [Lexer](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/Lexer.java): tokenizer · Converts source text into syntax tokens and lexer diagnostics. · `src/main/java/com/JsonAjax/justcompiler/Syntax/Lexer.java`
- [Parser](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/Parser.java): parser · Builds the compilation unit syntax tree from tokens. · `src/main/java/com/JsonAjax/justcompiler/Syntax/Parser.java`
- [Syntax Facts](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxFacts.java): language rules · Defines keywords, operators, precedence, and token metadata. · `src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxFacts.java`
- [Syntax Nodes](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxNode.java): ast model · Expression and statement node hierarchy for the parsed language. · `src/main/java/com/JsonAjax/justcompiler/Syntax/SyntaxNode.java`

### Binding

Semantic analysis and bound tree.

- [Binder](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/Binder.java): semantic analyzer · Resolves names, checks operators, and lowers syntax to bound nodes. · `src/main/java/com/JsonAjax/justcompiler/Binding/Binder.java`
- [Bound Scope](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundScope.java): scope model · Tracks variable visibility, shadowing, and redeclaration rules. · `src/main/java/com/JsonAjax/justcompiler/Binding/BoundScope.java`
- [Global Scope](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundGlobalScope.java): scope snapshot · Holds the top-level bound declarations for a compilation. · `src/main/java/com/JsonAjax/justcompiler/Binding/BoundGlobalScope.java`
- [Variable Symbol](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/VariableSymbol.java): symbol · Describes variables, including name, type, and mutability. · `src/main/java/com/JsonAjax/justcompiler/VariableSymbol.java`
- [Bound Ops](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundBinaryOperator.java): operator tables · Defines supported unary and binary operator bindings. · `src/main/java/com/JsonAjax/justcompiler/Binding/BoundBinaryOperator.java`
- [Bound Nodes](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Binding/BoundNode.java): bound tree · Executable semantic node hierarchy for expressions and statements. · `src/main/java/com/JsonAjax/justcompiler/Binding/BoundNode.java`

### Runtime

Execution of bound nodes.

- [Evaluator](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/Evaluator.java): runtime executor · Executes bound statements and expressions to produce a value. · `src/main/java/com/JsonAjax/justcompiler/Evaluator.java`
- [Eval Result](https://github.com/houssameddine-yousfi/justcompiler/blob/main/src/main/java/com/JsonAjax/justcompiler/EvaluationResult.java): result wrapper · Carries the computed value and any diagnostics from execution. · `src/main/java/com/JsonAjax/justcompiler/EvaluationResult.java`

## Connections

- Index → Compilation: runs · The driver creates and executes compilations for user input.
- Compilation → Syntax Tree: parses · Compilation starts by turning source text into a syntax tree.
- Syntax Tree → Lexer: uses · Tree construction depends on lexical tokenization.
- Syntax Tree → Parser: uses · Tree construction depends on parsing.
- Lexer → Source Text: reads · Lexing consumes the original source text.
- Lexer → Syntax Facts: consults · Tokenization and precedence decisions use language facts.
- Parser → Syntax Nodes: builds · The parser creates concrete syntax nodes.
- Parser → Syntax Facts: consults · Parsing uses token kinds and precedence rules.
- Source Text → Text Line: maps · Source text is segmented into lines for diagnostics.
- Source Text → Text Span: supports · Span locations reference positions within source text.
- Syntax Tree → Diagnostics: reports · Syntax tree creation collects parse diagnostics.
- Lexer → Diagnostics: reports · Lexical errors are accumulated as diagnostics.
- Parser → Diagnostics: reports · Parsing errors are accumulated as diagnostics.
- Compilation → Binder: binds · Compilation lowers syntax to semantically checked bound nodes.
- Binder → Bound Scope: uses · The binder manages nested scopes and symbol visibility.
- Binder → Global Scope: produces · Binding produces the top-level scope snapshot.
- Binder → Variable Symbol: declares · Variables are represented as symbols during binding.
- Binder → Bound Ops: matches · Operator applicability is resolved through operator tables.
- Binder → Bound Nodes: creates · Syntax is lowered into bound statements and expressions.
- Bound Scope → Variable Symbol: contains · Scopes store declared variables.
- Compilation → Evaluator: executes · Compilation hands the bound tree to the evaluator.
- Evaluator → Bound Nodes: walks · Execution traverses the bound tree.
- Evaluator → Eval Result: returns · Evaluation produces a final result wrapper.
- Evaluator → Diagnostics: reports · Runtime and semantic failures surface through diagnostics.
- Eval Result → Diagnostic: contains · The result wrapper can carry reported issues.