# lyledean1/cyclang architecture

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

- Interactive diagram: https://gitdiagram.com/lyledean1/cyclang
- Repository: https://github.com/lyledean1/cyclang

## Overview

##### Project type and purpose
- Cyclang is a custom programming language implementation written in Rust.
- It consists of a command‑line compiler (and REPL), a PEG‑based parser, and an LLVM‑based backend that generates machine code.
- Its purpose is to read `.cyc` source files (or REPL input), parse them into an AST, perform semantic checks/codegen, and produce an executable.

##### File structure
- Top‐level crates folder holds three Rust crates:
– cyclang‑parser: grammar and parsing logic (uses Pest)
– cyclang‑backend: compiler pipeline, semantic context, code generation modules, stdlib embedding
– cyclang: the CLI driver and REPL entry point
- examples/ contains sample `.cyc` programs.
- book/ holds generated documentation (user guide).
- Dev environment: Docker (devcontainer), GitHub Actions, Makefile for LLVM setup.

##### Core architecture (compiler pipeline)
We can abstract the run of `cyclang --file foo.cyc` into the following stages:
1. CLI Driver (crates/cyclang/src/main.rs)
– Parses command‑line flags, selects file or REPL mode
2. Parser (crates/cyclang-parser)
– Reads source text → Pest grammar → Concrete parse tree → converts to AST
3. Semantic Context & Analysis (in cyclang-backend/src/compiler/context.rs)
– Type checking, symbol resolution, scope management
4. Intermediate Representation & CodeGen (cyclang-backend/src/compiler/codegen)
– Builds LLVM IR via llvm-sys bindings
– Embeds stdlib modules (list, string)
– Target abstraction (cyclang-backend/src/compiler/codegen/target.rs)
– Caching layer to avoid repeated builds
5. LLVM Optimization & Code Emission (via llvm-sys linking to libLLVM-19)
6. Native Binary Output or JIT Execution (for REPL)

##### Special guidance for a compiler‐style project
- Lay out the compiler stages in left‑to‑right (or top‑to‑bottom) sequence.
- External dependencies (Pest grammar file, LLVM library).
- How stdlib IR artifacts are loaded/generated.
- Optional REPL flow branching from the driver to a JIT execution path.

##### Essential details without clutter
- Major modules with their crate name (e.g., “cyclang-parser crate”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    Source[".cyc Source / REPL Input"]:::input

    subgraph "CLI (cyclang crate)"
        CLI_Main["Main"]:::frontend
        CLI_Repl["REPL"]:::frontend
        CLI_Build["Build Script"]:::infra
    end

    subgraph "Parser Stage"
        Parser["Parser Module (Pest)"]:::parsing
    end

    subgraph "AST & Semantic"
        Analyzer["Semantic Analyzer"]:::semantic
    end

    subgraph "Code Generation"
        CodeGen["CodeGen Module"]:::codegen
        subgraph "Stdlib Resources"
            Std_List["list.rs"]:::external
            Std_String["string.rs"]:::external
            Std_TypesBC["types.bc"]:::external
            Std_TypesC["types.c"]:::external
        end
    end

    Cache["Caching Layer"]:::external
    LLVM["LLVM Library (llvm-sys)"]:::external

    Output_Bin["Output Binary"]:::output
    Output_REPL["REPL Console"]:::output

    subgraph "Dev & Build Infrastructure"
        Docker["Docker Devcontainer"]:::infra
        CI["GitHub Actions"]:::infra
        Make["Makefile"]:::infra
        Cargo{"Cargo.toml"}:::infra
    end

    %% Connections
    Source --> CLI_Main
    Source --> CLI_Repl

    CLI_Main --> Parser
    CLI_Repl --> Parser

    Parser --> Analyzer

    Analyzer --> CodeGen

    CodeGen --> LLVM
    LLVM --> Output_Bin
    CLI_Repl --> Output_REPL

    CodeGen --> Std_List
    CodeGen --> Std_String
    CodeGen --> Std_TypesBC
    CodeGen --> Std_TypesC

    CodeGen -.-> Cache

    Docker --> Cargo
    CI --> Cargo
    Make --> Cargo

    Cargo --> CLI_Main
    Cargo --> Parser
    Cargo --> Analyzer
    Cargo --> CodeGen

    %% Click Events
    click CLI_Main "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang/src/main.rs"
    click CLI_Repl "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang/src/repl.rs"
    click CLI_Build "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang/build.rs"
    click Parser "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-parser/src/lib.rs"
    click Parser "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-parser/grammar/cyclo.pest"
    click Analyzer "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/context.rs"
    click Analyzer "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/visitor.rs"
    click Analyzer "https://github.com/lyledean1/cyclang/tree/main/crates/cyclang-backend/src/compiler/types"
    click CodeGen "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/mod.rs"
    click CodeGen "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/builder.rs"
    click CodeGen "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/context.rs"
    click CodeGen "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/target.rs"
    click LLVM "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/lib.rs"
    click LLVM "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/Cargo.toml"
    click Std_List "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/stdlib/list.rs"
    click Std_String "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/stdlib/string.rs"
    click Std_TypesBC "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/stdlib/types.bc"
    click Std_TypesC "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/codegen/stdlib/types.c"
    click Cache "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang-backend/src/compiler/cache.rs"
    click Output_Bin "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang/src/main.rs"
    click Output_REPL "https://github.com/lyledean1/cyclang/blob/main/crates/cyclang/src/repl.rs"
    click Docker "https://github.com/lyledean1/cyclang/tree/main/.devcontainer/"
    click CI "https://github.com/lyledean1/cyclang/blob/main/.github/workflows/main.yaml"
    click Make "https://github.com/lyledean1/cyclang/tree/main/Makefile"
    click Cargo "https://github.com/lyledean1/cyclang/blob/main/Cargo.toml"

    %% Styles
    classDef parsing fill:#BBDEFB,stroke:#000
    classDef semantic fill:#C8E6C9,stroke:#000
    classDef codegen fill:#FFCCBC,stroke:#000
    classDef external fill:#E0E0E0,stroke:#000
    classDef infra fill:#CFD8DC,stroke:#000
    classDef frontend fill:#BBDEFB,stroke:#000
    classDef output fill:#D1C4E9,stroke:#000
    classDef input fill:#FFF9C4,stroke:#000
```
