# alissonbrunosa/iracema architecture

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

- Interactive diagram: https://gitdiagram.com/alissonbrunosa/iracema
- Repository: https://github.com/alissonbrunosa/iracema

## Overview

##### Project type and purpose
- This is a language implementation project (named “Iracema”) written in Go.
- It provides a compiler and bytecode‐based interpreter for a small object‐oriented scripting language.
- Key features: Lexer, Parser, AST, a compiler that emits bytecode, and a virtual machine/ interpreter with built-in types and functions.

##### File structure
- Top-level
- cmd/iracema: entry point (CLI)
- lexer/: lexical analyzer
- parser/: produces an AST from tokens
- ast/: AST node definitions
- compile/: backend, IR optimization, bytecode emitter, disassembler
- bytecode/: opcode definitions and string representations
- interpreter/: virtual machine, stack frames, bytecode execution
- lang/: standard library, built-in types (objects, methods, utils)
- token/: token types and position tracking
- examples/: sample .ir programs
- c/: unrelated C-language parser/lexer in C (likely experimental or comparison)

##### README for additional insights
- README shows sample Iracema syntax and operators.
- Confirms this is a full compiler+VM pipeline in Go 1.17+.

a. Main components
- CLI Frontend (cmd/iracema)
- Lexer (lexer package)
- Parser & AST (parser + ast packages)
- Compiler Backend (compile package)
- Bytecode Format (bytecode package)
- Virtual Machine / Interpreter (interpreter package)
- Runtime & Standard Library (lang package)
- Token definitions (token package)
- Example inputs (examples/*.ir)
b. Relationships & data flow
1. User invokes CLI →
2. CLI reads source file & hands it to Lexer →
3. Lexer emits Token stream →
4. Parser consumes tokens → constructs AST nodes →
5. Compiler walks AST → builds basic blocks/IR → emits Bytecode →
6. Interpreter loads bytecode → executes on its VM (Frame, Stack) →
7. Interpreter invokes built-in functions/objects in lang package →
8. Output to stdio (e.g. puts())
c. Architectural patterns & design principles
- Pipeline architecture: front end (lex/parse/AST) → middle end (IR/opt) → back end (bytecode emitter/VM)
- Visitor/pattern matching in AST and compiler (match_helpers_test.go)
- Separation of concerns: each package has a single responsibility
- Test-driven: almost every package has its own *_test.go
d. Key technologies
- Go modules (go.mod)
- Go 1.17+
- Command-line binary (cmd/iracema)
- Optional disassembler tool (compile/disassemble.go)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers
    subgraph "Front End"
        direction TB
        Examples["Example .ir Programs"]:::external
        CLI["CLI Frontend"]:::frontend
        Lexer["Lexer"]:::frontend
        Token["Token Definitions"]:::frontend
        Parser["Parser"]:::frontend
        AST["AST Node Definitions"]:::frontend
    end

    subgraph "Middle End"
        direction TB
        IR["IR & Basic Blocks"]:::middle
        Compiler["Compiler Driver"]:::middle
        Disassembler["Disassembler Tool"]:::middle
        Bytecode["Bytecode Format"]:::middle
    end

    subgraph "Back End / Runtime"
        direction TB
        Interpreter["Interpreter / VM"]:::backend
        Frame["Stack Frame"]:::backend
        Runtime["Runtime & Std Library"]:::backend
    end

    LegacyC["Legacy C Parser/Lexer"]:::external

    %% Connections
    Examples --> CLI
    CLI -->|"source (.ir)"| Lexer
    Lexer -->|"Tokens"| Parser
    Parser -->|"AST"| AST
    AST -->|"AST Nodes"| Compiler
    Compiler -->|"IR"| IR
    IR -->|"Bytecode"| Bytecode
    Compiler -->|"disassemble"| Disassembler
    Bytecode -->|"bytecode file"| Interpreter
    Interpreter --> Frame
    Interpreter -->|"built-ins"| Runtime
    LegacyC -.-> Lexer

    %% Click Events
    click CLI "https://github.com/alissonbrunosa/iracema/blob/main/cmd/iracema/main.go"
    click Lexer "https://github.com/alissonbrunosa/iracema/blob/main/lexer/lexer.go"
    click Token "https://github.com/alissonbrunosa/iracema/blob/main/token/token.go"
    click Parser "https://github.com/alissonbrunosa/iracema/blob/main/parser/parser.go"
    click AST "https://github.com/alissonbrunosa/iracema/blob/main/ast/ast.go"
    click IR "https://github.com/alissonbrunosa/iracema/blob/main/compile/basicblock.go"
    click Compiler "https://github.com/alissonbrunosa/iracema/blob/main/compile/compile.go"
    click Disassembler "https://github.com/alissonbrunosa/iracema/blob/main/compile/disassemble.go"
    click Bytecode "https://github.com/alissonbrunosa/iracema/blob/main/bytecode/opcode.go"
    click Interpreter "https://github.com/alissonbrunosa/iracema/blob/main/interpreter/interpreter.go"
    click Frame "https://github.com/alissonbrunosa/iracema/blob/main/interpreter/frame.go"
    click Runtime "https://github.com/alissonbrunosa/iracema/tree/main/lang/"
    click Examples "https://github.com/alissonbrunosa/iracema/blob/main/examples/conditional.ir"
    click LegacyC "https://github.com/alissonbrunosa/iracema/blob/main/c/lexer.c"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef middle fill:#FFD8B0,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef external fill:#EEEEEE,stroke-dasharray: 2 2,stroke:#666
```
