# servostar/gemstone architecture

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

- Interactive diagram: https://gitdiagram.com/servostar/gemstone
- Repository: https://github.com/servostar/gemstone

## Overview

##### Main Components

a) Compiler Pipeline Components:
- Lexical Analysis (using Flex)
- Syntax Analysis (using Bison)
- Semantic Analysis
- LLVM Code Generation
- Linking System (Clang/GCC)

b) Supporting Systems:
- Build System (CMake-based)
- Standard Library Components
- Testing Framework
- Docker Infrastructure

##### Detailed Component Breakdown

Layer 1 - Core Compiler Pipeline:
**[Source Files] -> [Lexer (Flex)] -> [Parser (Bison)] -> [AST Generator] -> [LLVM IR Generator] -> [Backend (LLVM)] -> [Linker (Clang/GCC)]**

Layer 2 - Standard Library System:
**[lib/**
- math
- io
- os
- mem
- std]

Layer 3 - Build & Testing Infrastructure:
**[Docker Containers] -> [CMake Build System] -> [Test Suite]**

##### Specific Implementation Details

a) Component Interactions:
- How the AST is built and transformed
- Import/include resolution process
- Demonstrate the library/executable output paths

b) Build Pipeline:
- Docker container hierarchy (Alpine -> SDK -> Devkit)
- CMake configuration flow
- Test integration points

##### Key Architectural Elements to Highlight

- Non-reentrant compiler design
- Linear flow of components
- LALR parsing capability
- Cross-compilation support
- Standard library integration
- Docker-based build isolation

Create distinct sections for:

##### Additional Notes

- Annotations for important configuration files
- Relationship between the build system and compiler components
- Where optimization passes occur
- Entry points for different build targets (library vs. executable)

This architecture should be represented as a combination of:

Each of these can be separate but interconnected views of the same system, providing a complete picture of the Gemstone compiler's architecture.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        L1[Core Compiler Component]:::compiler
        L2[Standard Library]:::stdlib
        L3[Build System]:::build
        L4[External Dependency]:::external
        L5[Infrastructure]:::infra
    end

    subgraph "Compiler Pipeline"
        Source[Source Files]:::compiler
        Lexer["Lexical Analysis (Flex)"]:::compiler
        Parser["Syntax Analysis (Bison)"]:::compiler
        AST["AST Generator"]:::compiler
        LLVMIR["LLVM IR Generator"]:::compiler
        Backend["LLVM Backend"]:::compiler
        Linker["Linker (Clang/GCC)"]:::compiler
        Output["Compiled Output"]:::compiler

        Source --> Lexer
        Lexer --> Parser
        Parser --> AST
        AST --> LLVMIR
        LLVMIR --> Backend
        Backend --> Linker
        Linker --> Output
    end

    subgraph "Standard Library"
        Math["Math Library"]:::stdlib
        IO["I/O Library"]:::stdlib
        OS["OS Library"]:::stdlib
        Mem["Memory Library"]:::stdlib
        Std["Standard Library"]:::stdlib
    end

    subgraph "Build System"
        Docker["Docker Containers"]:::infra
        CMake["CMake Build System"]:::build
        Tests["Test Suite"]:::build
    end

    subgraph "External Dependencies"
        LLVM["LLVM Framework"]:::external
        GLib["GLib"]:::external
        CompilerTools["Clang/GCC"]:::external
    end

    subgraph "Core Components"
        CompilerCore["Compiler Core"]:::compiler
        MemManager["Memory Manager"]:::compiler
        CodeGen["Code Generator"]:::compiler
    end

    CompilerCore --> Lexer
    CompilerCore --> Parser
    CodeGen --> LLVMIR
    MemManager --> CompilerCore

    Docker --> CMake
    CMake --> CompilerCore
    CMake --> Tests

    Backend --> LLVM
    Linker --> CompilerTools

    %% Click events for component mapping
    click Lexer "https://github.com/servostar/gemstone/blob/main/src/lex/lexer.l"
    click Parser "https://github.com/servostar/gemstone/blob/main/src/yacc/parser.y"
    click AST "https://github.com/servostar/gemstone/blob/main/src/ast/ast.h"
    click Backend "https://github.com/servostar/gemstone/blob/main/src/llvm/backend.c"
    click Linker "https://github.com/servostar/gemstone/blob/main/src/link/lib.h"
    click Math "https://github.com/servostar/gemstone/tree/main/lib/src/math/"
    click IO "https://github.com/servostar/gemstone/tree/main/lib/src/io/"
    click OS "https://github.com/servostar/gemstone/tree/main/lib/src/os/"
    click Mem "https://github.com/servostar/gemstone/tree/main/lib/src/mem/"
    click Std "https://github.com/servostar/gemstone/blob/main/lib/src/std.gsc"
    click Docker "https://github.com/servostar/gemstone/tree/main/Dockerfile"
    click CMake "https://github.com/servostar/gemstone/blob/main/CMakeLists.txt"
    click Tests "https://github.com/servostar/gemstone/tree/main/tests/"
    click CodeGen "https://github.com/servostar/gemstone/blob/main/src/codegen/backend.c"
    click MemManager "https://github.com/servostar/gemstone/blob/main/src/mem/cache.c"
    click CompilerCore "https://github.com/servostar/gemstone/blob/main/src/compiler.c"

    classDef compiler fill:#3498db,stroke:#2980b9,color:white
    classDef stdlib fill:#2ecc71,stroke:#27ae60,color:white
    classDef build fill:#e67e22,stroke:#d35400,color:white
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d,color:white
```
