# fruits-lab/vitaminc architecture

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

- Interactive diagram: https://gitdiagram.com/fruits-lab/vitaminc
- Repository: https://github.com/fruits-lab/vitaminc

## Overview

##### Project Type and Purpose
- The project is a compiler frontend aimed at demonstrating how a C compiler works. It handles compilation phases (lexer, parser, type checker, IR generator) and produces both QBE and LLVM IR.
- Key points from the README include its target IRs, support for C89 (with some C99 features), and the usage of LLVM’s compiler infrastructure alongside QBE.

##### File Structure
- Top-level files indicate configuration (.clang-format, .clang-tidy, Makefile, etc.), and the entry point is main.cpp.
- The presence of lexer.l and parser.y immediately indicates the implementation of the lexical analyzer (likely using Lex/Flex) and parser (using Yacc/Bison).
- The include/ and src/ directories contain header and source files respectively for the core components:
- AST: Files such as ast.hpp/ast.cpp and ast_dumper help in building and visualizing the AST.
- Type Checker: Files type_checker.hpp/type_checker.cpp.
- Symbol management, scope handling, and utility functions are also clearly separated.
- IR Generators: There are separate files and directories for llvm_ir_generator and qbe_ir_generator in both include and src.
- The test directory is well-organized into subdirectories for testing code generation and type checking, providing compiled examples (.c) and expected output (.exp) files. This shows that the project has strong testing infrastructure to validate the individual compilation stages.

##### Components
a. Main Components:
- Command-Line Interface & Driver Component: Represented by main.cpp; handles command-line options (using cxxopts), directing the input file to the subsequent phases.
- Lexical Analyzer: Based on lexer.l — responsible for tokenizing the input.
- Parser: Based on parser.y — builds the initial AST from tokens.
- Abstract Syntax Tree (AST): Comprising classes defined in ast.hpp/ast.cpp, and with support for dumping/debugging using ast_dumper.
- Type Checker: Responsible for semantic analysis; included in type_checker.hpp/type_checker.cpp.
- IR Generators: This branch splits into:
▪ LLVM IR Generator – uses LLVM libraries (see include/llvm_ir_generator.hpp/llvm_ir_generator.cpp and related utility code in src/llvm).
▪ QBE IR Generator – uses QBE-specific constructs (visible via include/qbe_ir_generator.hpp and src/qbe_ir_generator.cpp).
- Support Utility Modules: Include modules for symbol management (symbol.hpp/cpp), scope handling, and common utilities (util.hpp/cpp).

b. Relationships and Interactions:
- Data Flow: The input file is first processed by the Lexical Analyzer, then the Parser, which constructs the AST.
- The AST is then passed to the Type Checker for semantic validation.
- Depending on the command-line target option (via --target), the type-checked AST is handed to either the LLVM IR Generator or QBE IR Generator.
- Data flows sequentially from one compilation phase to the next, with each phase encapsulated as a distinct component.
- The testing framework (located in the test/ directory) validates code generation and type checking by comparing generated IR with expected outputs.

c. Architectural Patterns and Design Principles:
- Modularity and Separation of Concerns: Each compilation phase is separated into distinct classes and source files.
- Pipeline Architecture: The design forms a clear pipeline (Lexer → Parser → AST → Type Checker → IR Generation).
- Extensibility: The design is structured to allow additional IR targets or compiler phases to be incorporated with minimal coupling.
- Use of External Tools/Dependencies: Indicates integration with LLVM and QBE for IR generation, plus additional libraries such as cxxopts for argument parsing and fmt for formatting.

d. Relevant Technologies and Frameworks:
- C++17 for modern features.
- Lex/Flex and Yacc/Bison for lexical and syntactic analysis.
- LLVM and QBE for IR generation and further compilation.
- cxxopts and fmt libraries.
- GNU Make for building the project.
- Testing tools like turnt are used for snapshot tests in the test directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Input File"]:::core
    B["CLI/Driver (main.cpp)"]:::core
    C["Lexical Analyzer (lexer.l)"]:::core
    D["Parser (parser.y)"]:::core
    E["AST (ast.hpp, ast.cpp, ast_dumper)"]:::core
    F["Type Checker (type_checker)"]:::core
    G{"TargetSelection"}:::decision
    H["LLVM IR Generator"]:::core
    I["QBE IR Generator"]:::core
    J["LLVM"]:::external
    K["QBE"]:::external
    L["Testing Framework"]:::testing

    subgraph "Support Utilities"
        M["Symbol Management"]:::support
        N["Scope Management"]:::support
        O["Common Utilities"]:::support
    end

    %% Main compilation pipeline
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G -- "LLVM" --> H
    G -- "QBE" --> I
    H --> J
    I --> K
    %% Integration with support utilities (dotted connections)
    E --- M:::support
    E --- N:::support
    E --- O:::support
    F --- M:::support
    F --- N:::support
    F --- O:::support
    %% Testing connections (dashed lines)
    F -.-> L:::testing
    H -.-> L:::testing
    I -.-> L:::testing

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef support fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef decision fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef testing fill:#ffcdd2,stroke:#c62828,stroke-width:2px;

    %% Click Events for CLI/Driver
    click B "https://github.com/fruits-lab/vitaminc/blob/main/main.cpp"

    %% Click Events for Lexical Analyzer
    click C "https://github.com/fruits-lab/vitaminc/blob/main/lexer.l"

    %% Click Events for Parser
    click D "https://github.com/fruits-lab/vitaminc/blob/main/parser.y"

    %% Click Events for AST (multiple mappings)
    click E "https://github.com/fruits-lab/vitaminc/blob/main/include/ast.hpp"
    click E "https://github.com/fruits-lab/vitaminc/blob/main/src/ast.cpp"
    click E "https://github.com/fruits-lab/vitaminc/blob/main/include/ast_dumper.hpp"
    click E "https://github.com/fruits-lab/vitaminc/blob/main/src/ast_dumper.cpp"

    %% Click Events for Type Checker
    click F "https://github.com/fruits-lab/vitaminc/blob/main/include/type_checker.hpp"
    click F "https://github.com/fruits-lab/vitaminc/blob/main/src/type_checker.cpp"

    %% Click Events for LLVM IR Generator
    click H "https://github.com/fruits-lab/vitaminc/blob/main/include/llvm_ir_generator.hpp"
    click H "https://github.com/fruits-lab/vitaminc/blob/main/src/llvm_ir_generator.cpp"
    click H "https://github.com/fruits-lab/vitaminc/tree/main/include/llvm"
    click H "https://github.com/fruits-lab/vitaminc/tree/main/src/llvm"

    %% Click Events for QBE IR Generator
    click I "https://github.com/fruits-lab/vitaminc/blob/main/include/qbe_ir_generator.hpp"
    click I "https://github.com/fruits-lab/vitaminc/blob/main/src/qbe_ir_generator.cpp"
    click I "https://github.com/fruits-lab/vitaminc/tree/main/include/qbe"

    %% Click Events for Support Utilities
    click M "https://github.com/fruits-lab/vitaminc/blob/main/include/symbol.hpp"
    click M "https://github.com/fruits-lab/vitaminc/blob/main/src/symbol.cpp"
    click N "https://github.com/fruits-lab/vitaminc/blob/main/include/scope.hpp"
    click N "https://github.com/fruits-lab/vitaminc/blob/main/src/scope.cpp"
    click O "https://github.com/fruits-lab/vitaminc/blob/main/include/util.hpp"
    click O "https://github.com/fruits-lab/vitaminc/blob/main/src/util.cpp"
```
