# aftermath22/oxygen_a-compiled-mini-language architecture

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

- Interactive diagram: https://gitdiagram.com/aftermath22/oxygen_a-compiled-mini-language
- Repository: https://github.com/aftermath22/oxygen_a-compiled-mini-language

## Overview

##### Project Type and Purpose
- This is a small, standalone compiler for the “Oxygen” programming language.
- It implements a traditional three-stage compilation pipeline:
- Lexical Analysis (tokenization)
- Parsing (AST construction)
- Code Generation (x86_64 assembly → object file → executable)

##### High-Level File / Directory Analysis
- Top-level files:
- CMakeLists.txt: build orchestration
- README.md, LICENSE: documentation
- main (executable stub?)
- test.oxy: sample source
- src/ directory: C++ source and headers
- main.cpp: compiler entry point, command-line interface
- tokenization.hpp: Lexer
- parser.hpp: Recursive-descent Parser → AST
- generation.hpp: Code Generator → x86_64 assembly
- arena.hpp: Custom bump-allocator for AST nodes

a. Front-end (CLI & Build)
- Inputs: `.oxy` source file
- CMake / build system invoking the compiler
b. Lexer (tokenization.hpp)
- Reads characters → produces Token stream
c. Parser (parser.hpp)
- Consumes Token stream → builds AST in memory
- Uses Arena Allocator for node allocation
d. Arena Allocator (arena.hpp)
- Pre-allocates large memory block
- Provides very fast bump allocations for AST nodes
e. AST Representation
- Variant-based node types (expressions, statements, etc.)
f. Code Generator (generation.hpp)
- Traverses AST → emits x86_64 assembly (`out.asm`)
- Manages stack frame, registers, scope offsets
g. External Tools
- NASM assembler: `out.asm` → `out.o`
- LD linker: `out.o` → final executable (`out`)
h. Error Handling Subsystem
- Reports line numbers / messages at lexer/parser stages

##### Interactions and Data Flow
1. User invokes `oxy input.oxy` (main.cpp)
2. main.cpp calls Lexer → produces Token stream
3. Token stream passed to Parser → constructs AST (arena-backed)
4. AST passed to Code Generator → writes assembly file
5. Assembly file fed to NASM → object file
6. Object file fed to LD → final executable
7. Any errors bubble up through each stage with contextual info

##### Architectural Patterns & Principles
- Pipeline Architecture: clear stage separation (Lex → Parse → Generate)
- Recursive Descent Parser: hand-written, precedence management
- Bump Allocator (Arena): bulk allocate AST nodes, free all at once
- Visitor-like traversal in Code Generator
- Modular separation: each component in its own header

- Optional numbering of steps to guide a viewer through the pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & CLI
    subgraph "Build & CLI"
        direction TB
        CMake["CMakeLists.txt"]:::build
        CLI["Compiler CLI\n(src/main.cpp)"]:::module
    end
    CMake -->|"configures"| CLI

    %% Sample Input
    SampleInput["sample input\n(test.oxy)"]:::io
    SampleInput -->|"file"| CLI
    click SampleInput "https://github.com/aftermath22/oxygen_a-compiled-mini-language/blob/master/test.oxy"

    %% Pipeline Stages
    subgraph "Lexical Analysis"
        direction TB
        Lexer["Lexer\n(src/tokenization.hpp)"]:::module
    end
    CLI -->|"reads source"| Lexer
    click Lexer "https://github.com/aftermath22/oxygen_a-compiled-mini-language/blob/master/src/tokenization.hpp"
    Lexer -->|"Token Stream"| Parser
    Lexer -.->|"errors"| CLI

    subgraph "Parsing & AST Construction"
        direction TB
        Parser["Parser + AST\n(src/parser.hpp)"]:::module
        Arena["Arena Allocator\n(src/arena.hpp)"]:::module
    end
    click Parser "https://github.com/aftermath22/oxygen_a-compiled-mini-language/blob/master/src/parser.hpp"
    click Arena "https://github.com/aftermath22/oxygen_a-compiled-mini-language/blob/master/src/arena.hpp"
    Parser -->|"allocates nodes"| Arena
    Parser -->|"AST in Arena"| Generator
    Parser -.->|"errors"| CLI

    subgraph "Code Generation"
        direction TB
        Generator["Code Generator\n(src/generation.hpp)"]:::module
    end
    click Generator "https://github.com/aftermath22/oxygen_a-compiled-mini-language/blob/master/src/generation.hpp"
    Generator -->|"writes out.asm"| NASM

    %% External Tools
    subgraph "External Toolchain"
        direction TB
        NASM["NASM Assembler"]:::tool
        LD["LD Linker"]:::tool
    end
    NASM -->|"out.o"| LD
    click NASM "https://github.com/aftermath22/oxygen_a-compiled-mini-language/tree/master/n/a"
    click LD "https://github.com/aftermath22/oxygen_a-compiled-mini-language/tree/master/n/a"
    LD -->|"executable (out)"| EndExec["Executable\n(out)"]:::output

    %% Documentation
    subgraph "Documentation"
        direction TB
        Readme["README.md"]:::build
        License["LICENSE"]:::build
    end
    click Readme "https://github.com/aftermath22/oxygen_a-compiled-mini-language/blob/master/README.md"
    click License "https://github.com/aftermath22/oxygen_a-compiled-mini-language/tree/master/LICENSE"

    %% Classes
    classDef module fill:#a2d5c6,stroke:#333,stroke-width:1px;
    classDef tool fill:#9ec1cf,stroke:#333,stroke-width:1px;
    classDef build fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef io fill:#f7cac9,stroke:#333,stroke-width:1px;
```
