# c3lang/c3c architecture

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

- Interactive diagram: https://gitdiagram.com/c3lang/c3c
- Repository: https://github.com/c3lang/c3c

## Overview

##### Main Components
- Compiler Core – This includes the front-end and back-end stages found in the “src/compiler” directory. Highlight modules such as the lexer, parser, AST construction, semantic analysis (sema_* files), and multiple code generation modules (e.g. LLVM codegen, assembly code generation, C code generation). Also note auxiliary compiler components such as the module system, macro system, and error handling (for “Result”-based error handling and contracts).
- Standard Library – Point out the “lib/std” directory which houses the implementation of the standard library for C3 and covers many subdomains (collections, crypto, io, math, net, etc.).
- Build and Infrastructure Systems – Include directories like “src/build”, “CMakeLists.txt”, “build-with-docker.sh”, “flake.nix”, and “nix/” which pertain to building the compiler and its libraries for various platforms.
- Testing Suite – Emphasize the “test” directory with its unit tests, compiler tests, and regression tests. This demonstrates how the compiler is verified using extensive test cases spread over many categories (e.g., tests for expressions, macros, and language features).
- Dependencies and External Libraries – Mention the “dependencies” folder (for instance, the miniz library) and the “wrapper” directory for C++ interoperability (e.g., LLVM wrappers), which indicate integration with third-party code.
- Documentation and Examples – Include “README.md” and “resources” (examples, grammar, images, etc.) that provide context, usage examples, and visual aids for the language.

##### Relationships and Data Flow
- Out the compiler pipeline starting from source file input, progressing through lexical analysis (lexer, tokens), followed by syntactic parsing to build an AST, then semantic analysis, and culminating in multiple code generation paths (LLVM backend and/or assembly/C code generation).
– From “src/main.c” and driver code launching the compiler.
– Between “src/compiler/lexer”, “src/compiler/parser”, and subsequent semantic modules.
– From these modules into various code generation components such as “llvm_codegen”, “asm”, and “codegen_asm”.
- Connections between the compiler core and the standard library (lib/std) to indicate that the standard library is not only part of the runtime ecosystem but also integrated into some compile-time reflection and error handling.

##### Architectural Patterns and Design Principles
- Pipeline Model: The compiler’s structure follows a linear pipeline pattern – starting with lexing, parsing, semantic analysis, and then branching into different code generation techniques.
- Modularization: Clearly identify that the project splits concerns into separate modules (compiler, standard library, tests, build systems). Also, highlight the use of generics and modules in the language itself as inspiration for how the project’s own architecture is organized.
- Integration & Compatibility: Include a note about the deliberate design to stay close to C – which is visible in the build scripts, dependency handling, and the integration points (e.g., C interoperability modules in the “dependencies” and “wrapper” folders).

##### Relevant Technologies and Tools
- CMake (and related build configurations)
- Docker (via build-with-docker.sh)
- Nix (flake.nix, nix/ directories)
- LLVM and LLD integration (as seen in the “src/compiler/llvm_codegen” modules and the wrapper/)
- Unit testing frameworks and regression tests (via the “test” directory)
- Code style and quality tools (such as .clang-tidy, .editorconfig)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compiler Core Pipeline
    subgraph "Compiler Core"
        A1["Lexer"]:::core
        A2["Parser"]:::core
        A3["AST Construction"]:::core
        A4["Semantic Analysis"]:::core
        A5["LLVM Code Generation"]:::core
        A6["Assembly/C Code Generation"]:::core
    end

    %% Driver Input
    B1["Driver: src/main.c"]:::core

    %% Pipeline Flow
    B1 -->|"source_input"| A1
    A1 -->|"token_stream"| A2
    A2 -->|"syntax_tree"| A3
    A3 -->|"AST_for_analysis"| A4
    A4 -->|"generates_LLVM_IR"| A5
    A4 -->|"emits_Assembly/C_code"| A6

    %% Final Output
    O1["Compiled Output"]:::core
    A5 -->|"LLVM_IR"| O1
    A6 -->|"Assembly/C_Output"| O1

    %% Standard Library
    subgraph "Standard Library"
        S1["Standard Library (lib/std)"]:::std
    end

    %% Integration between Compiler and Standard Library
    A4 -->|"integrated_with"| S1

    %% Build and Infrastructure Systems
    subgraph "Build and Infrastructure"
        B2["Build System (src/build)"]:::build
        B3["CMake Configuration (CMakeLists.txt)"]:::build
        B4["Docker Build Script (build-with-docker.sh)"]:::build
        B5["Nix Flake (flake.nix)"]:::build
        B6["Nix Config (nix/)"]:::build
    end

    %% Build System Relationships
    B2 -->|"configured_by"| B3
    B2 -->|"supports"| B4
    B2 -->|"config_via"| B5
    B2 -->|"uses"| B6
    B2 -->|"builds"| O1
    B3 -->|"configures"| A4

    %% Testing Suite
    subgraph "Testing Suite"
        T1["Global Tests (test)"]:::test
    end

    %% Testing relationship
    T1 -->|"validates"| O1

    %% Dependencies and External Libraries
    subgraph "Dependencies and External Libraries"
        D1["Miniz & Others (dependencies)"]:::deps
        D2["LLVM/C++ Wrappers (wrapper)"]:::deps
    end

    %% Dependency Integration
    D2 -->|"integrated_with"| A5

    %% Documentation and Examples
    subgraph "Documentation & Examples"
        E1["Project Doc (README.md)"]:::docs
        E2["Resources & Examples (resources)"]:::docs
    end

    %% Documentation Relationships
    E1 -->|"guides"| B2
    E2 -->|"provides_examples_for"| O1

    %% Click Events for Compiler Core
    click A1 "https://github.com/c3lang/c3c/blob/master/src/compiler/lexer.c"
    click A2 "https://github.com/c3lang/c3c/blob/master/src/compiler/parser.c"
    click A3 "https://github.com/c3lang/c3c/blob/master/src/compiler/ast.c"
    click A5 "https://github.com/c3lang/c3c/tree/master/src/compiler/llvm_codegen"
    click A6 "https://github.com/c3lang/c3c/blob/master/src/compiler/codegen_asm.c"

    %% Click Events for Standard Library
    click S1 "https://github.com/c3lang/c3c/tree/master/lib/std"

    %% Click Events for Build and Infrastructure Systems
    click B2 "https://github.com/c3lang/c3c/tree/master/src/build"
    click B3 "https://github.com/c3lang/c3c/blob/master/CMakeLists.txt"
    click B4 "https://github.com/c3lang/c3c/blob/master/build-with-docker.sh"
    click B5 "https://github.com/c3lang/c3c/blob/master/flake.nix"
    click B6 "https://github.com/c3lang/c3c/tree/master/nix/"

    %% Click Events for Testing Suite
    click T1 "https://github.com/c3lang/c3c/tree/master/test"

    %% Click Events for Dependencies
    click D1 "https://github.com/c3lang/c3c/tree/master/dependencies"
    click D2 "https://github.com/c3lang/c3c/tree/master/wrapper"

    %% Click Events for Documentation and Examples
    click E1 "https://github.com/c3lang/c3c/blob/master/README.md"
    click E2 "https://github.com/c3lang/c3c/tree/master/resources"

    %% Styles for Differentiation
    classDef core fill:#ffcccc,stroke:#880000,stroke-width:2px;
    classDef std fill:#ccffcc,stroke:#008800,stroke-width:2px;
    classDef build fill:#ccccff,stroke:#000088,stroke-width:2px;
    classDef test fill:#ffffcc,stroke:#888800,stroke-width:2px;
    classDef deps fill:#ffccff,stroke:#880088,stroke-width:2px;
    classDef docs fill:#ccffff,stroke:#008888,stroke-width:2px;
```
