# crystal-lang/crystal architecture

> Architecture diagram of the GitHub repository crystal-lang/crystal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crystal-lang/crystal
- Repository: https://github.com/crystal-lang/crystal

## Overview

##### Main Components
The system should be divided into these major components:

a. Compiler Frontend
- Lexer (src/compiler/crystal/syntax/lexer.cr)
- Parser (src/compiler/crystal/syntax/parser.cr)
- AST (src/compiler/crystal/syntax/ast.cr)
- Semantic Analysis (src/compiler/crystal/semantic/)

b. Compiler Backend
- Code Generation (src/compiler/crystal/codegen/)
- LLVM Integration (src/llvm/)
- Interpreter (src/compiler/crystal/interpreter/)

c. Standard Library
- Core Types (src/*)
- Runtime Support (src/gc/, src/fiber/)
- Platform-specific Code (src/lib_c/)

d. Development Tools
- Package Manager
- Documentation Generator (src/compiler/crystal/tools/doc/)
- Formatter (src/compiler/crystal/tools/formatter.cr)

##### Relationships and Data Flow

**Source Code → Lexer → Parser → AST → Semantic Analysis → Code Generation → LLVM IR → Native Code**
- ↓
- Interpreter

##### Detailed Component Breakdown

For each major component, show:

a. Compiler Frontend:
**Lexer**
- Token Generation
- Source Location Tracking

**Parser**
- AST Construction
- Error Reporting

**Semantic Analysis**
- Type Inference
- Method Resolution
- Macro Expansion

b. Compiler Backend:
**Code Generation**
- LLVM IR Generation
- Optimization Passes
- Platform-specific Code

**LLVM Integration**
- Type System Mapping
- ABI Support
- Optimization Pipeline

##### Cross-cutting Concerns

As vertical layers affecting multiple components:
- Error Handling
- Debug Information
- Platform Abstraction
- Memory Management

##### External Dependencies

- LLVM
- LibGC (Boehm GC)
- Platform-specific Libraries

##### Development Environment Integration

Connections to:
- Build System
- Package Manager
- Testing Framework
- Documentation Generator

- Clear separation between compile-time and runtime components
- The multi-pass nature of the compiler
- Platform abstraction layers
- Integration points with external systems

- Component types
- Special symbols or notations

- Future expansion
- Platform-specific variations
- Optional components
- Development tool integration

This architecture should reflect Crystal's goals of:
- Ruby-like syntax
- Static type checking
- C code integration
- Compile-time evaluation
- Efficient native code generation

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Legend"
        L1[Compiler Component]:::compiler
        L2[Runtime Component]:::runtime
        L3[Development Tool]:::devtool
        L4[External Dependency]:::external
        L5[/"Data Flow"/]
    end

    subgraph "Compiler Frontend"
        SourceCode[/"Source Code"/]
        Lexer["Lexer"]:::compiler
        Parser["Parser"]:::compiler
        AST["AST"]:::compiler
        SemanticAnalysis["Semantic Analysis"]:::compiler
        
        subgraph "Semantic Details"
            TypeInference["Type Inference"]:::compiler
            MethodResolution["Method Resolution"]:::compiler
            MacroExpansion["Macro Expansion"]:::compiler
        end
    end

    subgraph "Compiler Backend"
        CodeGen["Code Generation"]:::compiler
        LLVM["LLVM Integration"]:::compiler
        Interpreter["Interpreter"]:::compiler
        
        subgraph "Code Generation Details"
            LLVMIR["LLVM IR Generation"]:::compiler
            OptPasses["Optimization Passes"]:::compiler
            PlatformCode["Platform-specific Code"]:::compiler
        end
    end

    subgraph "Standard Library"
        CoreTypes["Core Types"]:::runtime
        RuntimeSupport["Runtime Support"]:::runtime
        PlatformSpecific["Platform-specific Code"]:::runtime
        
        subgraph "Runtime Components"
            GC["Garbage Collection"]:::runtime
            Fiber["Fiber Support"]:::runtime
        end
    end

    subgraph "Development Tools"
        DocGen["Documentation Generator"]:::devtool
        Formatter["Formatter"]:::devtool
        PackageManager["Package Manager"]:::devtool
    end

    subgraph "External Dependencies"
        LLVMExt["LLVM"]:::external
        LibGC["LibGC (Boehm)"]:::external
        PlatformLibs["Platform Libraries"]:::external
    end

    subgraph "Cross-cutting Concerns"
        ErrorHandling["Error Handling"]
        DebugInfo["Debug Information"]
        PlatformAbs["Platform Abstraction"]
        MemoryMgmt["Memory Management"]
    end

    %% Main Flow
    SourceCode --> Lexer
    Lexer --> Parser
    Parser --> AST
    AST --> SemanticAnalysis
    SemanticAnalysis --> CodeGen
    CodeGen --> LLVM
    SemanticAnalysis --> Interpreter

    %% Semantic Analysis Details
    SemanticAnalysis --> TypeInference
    SemanticAnalysis --> MethodResolution
    SemanticAnalysis --> MacroExpansion

    %% Code Generation Details
    CodeGen --> LLVMIR
    CodeGen --> OptPasses
    CodeGen --> PlatformCode

    %% Runtime Connections
    RuntimeSupport --> GC
    RuntimeSupport --> Fiber

    %% External Dependencies
    LLVM --> LLVMExt
    GC --> LibGC
    PlatformSpecific --> PlatformLibs

    %% Style Definitions
    classDef compiler fill:#a8d1f0,stroke:#333
    classDef runtime fill:#90EE90,stroke:#333
    classDef devtool fill:#FFB347,stroke:#333
    classDef external fill:#D3D3D3,stroke:#333

    %% Click Events
    click Lexer "https://github.com/crystal-lang/crystal/blob/master/src/compiler/crystal/syntax/lexer.cr"
    click Parser "https://github.com/crystal-lang/crystal/blob/master/src/compiler/crystal/syntax/parser.cr"
    click AST "https://github.com/crystal-lang/crystal/blob/master/src/compiler/crystal/syntax/ast.cr"
    click SemanticAnalysis "https://github.com/crystal-lang/crystal/tree/master/src/compiler/crystal/semantic/"
    click CodeGen "https://github.com/crystal-lang/crystal/tree/master/src/compiler/crystal/codegen/"
    click LLVM "https://github.com/crystal-lang/crystal/tree/master/src/llvm/"
    click Interpreter "https://github.com/crystal-lang/crystal/tree/master/src/compiler/crystal/interpreter/"
    click CoreTypes "https://github.com/crystal-lang/crystal/tree/master/src/"
    click GC "https://github.com/crystal-lang/crystal/tree/master/src/gc/"
    click Fiber "https://github.com/crystal-lang/crystal/tree/master/src/fiber/"
    click PlatformSpecific "https://github.com/crystal-lang/crystal/tree/master/src/lib_c/"
    click DocGen "https://github.com/crystal-lang/crystal/tree/master/src/compiler/crystal/tools/doc/"
    click Formatter "https://github.com/crystal-lang/crystal/blob/master/src/compiler/crystal/tools/formatter.cr"
    click ErrorHandling "https://github.com/crystal-lang/crystal/blob/master/src/compiler/crystal/error.cr"
    click DebugInfo "https://github.com/crystal-lang/crystal/blob/master/src/compiler/crystal/codegen/debug.cr"
    click PlatformAbs "https://github.com/crystal-lang/crystal/tree/master/src/crystal/system/"
```
