# graysonhuey/auroralang architecture

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

- Interactive diagram: https://gitdiagram.com/graysonhuey/auroralang
- Repository: https://github.com/graysonhuey/auroralang

## Overview

##### Project type and purpose
- This is a compiler for the Aurora programming language, written in Rust.
- It takes a `.aur` source file, tokenizes it, generates x86-64 assembly, and then invokes FASM and LD to produce a runnable executable.

##### File structure
- Top-level files:
– Cargo.toml / Cargo.lock: Rust build and dependency manifest
– README.md, LICENSE: documentation
- `src/` directory:
– main.rs: entry point, CLI parsing, overall compilation workflow
– tokens.rs: lexical analysis (tokenizer)
– generateASM.rs: core code generation into x86-64 assembly
– utils.rs: shared constants, helper functions
- `tests/` directory:
– `.aur` test programs plus prebuilt binaries for gold-file testing
– A test harness in Rust likely under `tests/` (invokes the compiler, assembles, runs)

##### README for additional insights
- Compilation pipeline is linear: tokenization → assembly instruction generation → FASM assembly → LD linking
- Uses external tools: FASM (Flat Assembler) and LD (GNU Linker)
- No separate parsing/AST stage—tokens flow directly into code generator

##### Main components and their interactions
a. Components
1. User (CLI)
2. Compiler binary (Rust):
- CLI handler (main.rs)
- Tokenizer (tokens.rs)
- Code generator (generateASM.rs)
- Utilities (utils.rs)
3. External tools: FASM assembler, LD linker
4. File artifacts:
- Input: `.aur` source file
- Intermediate: `.asm` file, object file `.o`
- Output: final executable binary
5. Test harness (in `tests/`): drives end-to-end compilation and validation
b. Relationships / Data flow
– CLI invokes the compiler with a `.aur` file
– main.rs reads file → calls tokenizer → receives a stream of tokens
– code generator consumes tokens → emits x86-64 assembly text → writes `.asm`
– Rust process spawns FASM on `.asm` → produces `.o`
– Rust process spawns LD on `.o` → links into final executable
– Tests invoke the same pipeline, then run the produced binary and compare output to expected results
c. Architectural patterns / design principles
– Single-pass linear pipeline (no full AST, tokens go straight to codegen)
– Modular separation of concerns: CLI, lexing, codegen, utils
– Externalizing platform-specific assembly and linking to FASM/LD
d. Key technologies
– Rust (edition 2018)
– FASM (x86-64 assembler), GNU LD (linker)
– Cargo (build tool)

##### Diagramming recommendations
– Rounded rectangles for user and file artifacts
– Rectangles for internal compiler modules
– Hexagons or clouds for external services/tools (FASM, LD)
– Blue for CLI / user interaction
– Green for compiler internals
– Orange for external tools
– Gray for file artifacts
- Major utility or shared functionality (e.g., integer-printing helpers in utils.rs)

##### Essential elements
- Arrowheads to show data flow direction
- A note on the linear nature of the pipeline (no multi-pass AST)
- The test harness and its comparison against expected outputs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Input
    User["User / CLI"]:::user
    Source[".aur Source File"]:::artifact

    %% Compiler Internals
    subgraph "Compiler (Rust)"
        Main["CLI Handler\n(main.rs)"]:::internal
        Tokenizer["Tokenizer\n(tokens.rs)"]:::internal
        CodeGen["Code Generator\n(generateASM.rs)"]:::internal
        Utils["Utilities\n(utils.rs)"]:::internal
    end

    %% External Tools
    FASM["FASM Assembler"]:::external
    LD["LD Linker"]:::external

    %% Artifacts
    ASM["Assembly File (.asm)"]:::artifact
    Object["Object File (.o)"]:::artifact
    Exe["Executable Binary"]:::artifact

    %% Test Harness
    subgraph "Test Harness"
        TestHarness["Test Harness"]:::test
        TestSources["Test Source Files\n(tests/*.aur)"]:::artifact
        Golden["Golden Binaries\n(tests/binaries/)"]:::artifact
    end

    %% Data Flow
    User -->|"Invokes with .aur"| Main
    Main -->|"Reads file"| Source
    Main -->|"Calls tokenizer"| Tokenizer
    Tokenizer -->|"Token stream"| CodeGen
    CodeGen -->|"Uses utils"| Utils
    Utils -.->|"Helper functions"| CodeGen
    CodeGen -->|"Writes .asm"| ASM
    ASM -->|"assemble"| FASM
    FASM -->|"Produces .o"| Object
    Object -->|"link"| LD
    LD -->|"Produces executable"| Exe

    %% Test Flow
    TestHarness -->|"Uses test sources"| TestSources
    TestHarness -->|"Invokes compiler"| Main
    TestHarness -->|"Compares output to expected"| Golden

    %% Click Events
    click Main "https://github.com/graysonhuey/auroralang/blob/main/src/main.rs"
    click Tokenizer "https://github.com/graysonhuey/auroralang/blob/main/src/tokens.rs"
    click CodeGen "https://github.com/graysonhuey/auroralang/blob/main/src/generateASM.rs"
    click Utils "https://github.com/graysonhuey/auroralang/blob/main/src/utils.rs"
    click TestHarness "https://github.com/graysonhuey/auroralang/tree/main/tests/"
    click TestSources "https://github.com/graysonhuey/auroralang/blob/main/tests/*.aur"
    click Golden "https://github.com/graysonhuey/auroralang/tree/main/tests/binaries/"

    %% Styles
    classDef user fill:#8ecae6,stroke:#023047,color:#000000
    classDef internal fill:#a8dadc,stroke:#1d3557,color:#000000
    classDef external fill:#f4a261,stroke:#e76f51,color:#000000
    classDef artifact fill:#e0e0e0,stroke:#6c757d,color:#000000
    classDef test fill:#e76f51,stroke:#d62828,color:#000000
```
