# bbayazit16/cart architecture

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

- Interactive diagram: https://gitdiagram.com/bbayazit16/cart
- Repository: https://github.com/bbayazit16/cart

## Overview

##### Overall Components
- Compiler (located in the "cartc" directory): Responsible for the entire compilation pipeline from reading source files to generating LLVM IR (using Inkwell) and linking the output with the system’s C compiler.
- Language Server (in "cart-lsp"): Provides tooling support such as code-completion, error linting, etc., that integrate with editors.
- Standard Library (in "cart_std"): Implements core functionalities for the Cart language, which the compiled programs use.
- Grammar Definitions and Installation Scripts: The "grammar" directory hints at the formal language definitions, and the "install.sh" script sets up the environment.

##### Detailed Compiler Architecture
- Lexical Analysis: In "cartc/src/lexer", files like alpha.rs, common.rs, etc. indicate that lexical analysis is performed early in the pipeline.
- Parsing & AST Generation: The "cartc/src/parser" directory contains modules for declarations, expressions, statements, and patterns. Additionally, the "ast" directory suggests a transformation phase which might include lowering from raw AST into a more structured form.
- Semantic Analysis / HIR: In "cartc/src/hir" you see components like type checking (type_check.rs) and error analysis (errors.rs), indicating a subsequent semantic phase where the AST is transformed into a higher-level representation (HIR).
- Code Generation: Under "cartc/src/codegen", you see files responsible for generating LLVM IR components, such as declarations, expressions, and symbol table management. This module interfaces with the LLVM IR generation library (Inkwell).
- Context and Error Reporting: The "context" and "errors" modules provide supporting functionality for tracking file positions and making the error messages user-friendly.
- CLI/Driver: The "cartc/src/cli" and "cartc/src/main.rs" files indicate the command-line interface which drives the overall compilation process.

##### Key Interactions and Data Flow
- Source Code → Lexical Analysis (Tokenizer): The CLI accepts a Cart source file, which is then tokenized.
- Tokens → Parser: The parser module processes tokens into an Abstract Syntax Tree (AST).
- AST → Lowering and HIR: The AST is subsequently transformed (using lowering techniques) into a high-level intermediate representation.
- HIR → Code Generation: The code generation module then translates this intermediate representation into LLVM IR.
- LLVM IR → Native Code: External tools (Inkwell via LLVM and cc for linking) are used to generate machine code.
- Error Reporting: At each stage there is integration with error reporting modules, ensuring that lexical, syntactical, and semantic issues are clearly communicated.

The language server (cart-lsp) likely communicates with the compiler backend to provide real-time feedback, thus forming an external connection that supports interactive development.

##### Architectural Patterns and Technologies
- Modular Design: The project is modularized into clearly separated concerns (lexer, parser, AST/HIR, codegen, context, errors).
- Pipeline Architecture: The compiler flows from one stage to the next (tokenization to parsing to semantic analysis to code generation).
- External Dependencies: LLVM IR generation is performed via the Inkwell library, and linking is done via cc.
- Integration Points: The standard library (cart_std) is compiled separately and then linked during execution; the language server (cart-lsp) enhances the developer experience by integration with editors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Source File"]:::input --> B["Cart Compiler"]:::compiler
    B --> C["CLI/Driver"]:::frontend
    C --> D["Lexical Analysis"]:::frontend
    D --> E["Parser"]:::frontend
    E --> F["AST Generation"]:::frontend
    F --> G["Semantic Analysis/HIR"]:::backend
    G --> H["Code Generation"]:::backend
    H --> I["LLVM IR Generation (Inkwell)"]:::external
    I --> J["Linking (cc)"]:::external
    J --> K["Native Code Output"]:::output

    %% Error Reporting integration (dotted connections)
    D --- L["Context & Error Reporting"]:::support
    E --- L
    G --- L

    %% Language Server interaction
    M["Language Server"]:::languageServer
    M --- B

    %% Standard Library linkage
    N["Standard Library"]:::stdLib
    N --- J

    %% Additional configuration elements
    O["Grammar Definitions"]:::config
    P["Installation Script"]:::config

    %% Click Events for Compiler and its submodules
    click B "https://github.com/bbayazit16/cart/tree/main/cartc"
    click C "https://github.com/bbayazit16/cart/tree/main/cartc/src/cli"
    click C "https://github.com/bbayazit16/cart/blob/main/cartc/src/main.rs"
    click D "https://github.com/bbayazit16/cart/tree/main/cartc/src/lexer"
    click E "https://github.com/bbayazit16/cart/tree/main/cartc/src/parser"
    click F "https://github.com/bbayazit16/cart/tree/main/cartc/src/ast"
    click G "https://github.com/bbayazit16/cart/tree/main/cartc/src/hir"
    click H "https://github.com/bbayazit16/cart/tree/main/cartc/src/codegen"
    click L "https://github.com/bbayazit16/cart/tree/main/cartc/src/context"
    click L "https://github.com/bbayazit16/cart/tree/main/cartc/src/errors"
    click L "https://github.com/bbayazit16/cart/tree/main/cartc/src/reporter"
    click M "https://github.com/bbayazit16/cart/blob/main/cart-lsp/src/main.rs"
    click N "https://github.com/bbayazit16/cart/tree/main/cart_std/src"
    click O "https://github.com/bbayazit16/cart/tree/main/grammar"
    click P "https://github.com/bbayazit16/cart/blob/main/install.sh"

    %% Class Definitions for colors
    classDef input fill:#f4e842,stroke:#333,stroke-width:1px;
    classDef compiler fill:#89CFF0,stroke:#000,stroke-width:1px;
    classDef frontend fill:#A9DFBF,stroke:#333,stroke-width:1px;
    classDef backend fill:#F5B7B1,stroke:#333,stroke-width:1px;
    classDef external fill:#F0B27A,stroke:#333,stroke-width:1px;
    classDef output fill:#A2D9CE,stroke:#333,stroke-width:1px;
    classDef support fill:#D2B4DE,stroke:#333,stroke-width:1px;
    classDef languageServer fill:#CCD1D1,stroke:#333,stroke-width:1px;
    classDef stdLib fill:#A3E4D7,stroke:#333,stroke-width:1px;
    classDef config fill:#F7DC6F,stroke:#333,stroke-width:1px;
```
