# chigraph/chigraph architecture

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

- Interactive diagram: https://gitdiagram.com/chigraph/chigraph
- Repository: https://github.com/chigraph/chigraph

## Overview

##### Project Type and Purpose
- Chigraph is a compiler‐style language project (systems programming language) made up of:
- A CLI tool (“chi”)
- A core library (libchigraph) for parsing, graph representation, codegen (to LLVM IR)
- A debugger support library (libchigraphdebugger)
- It fetches remote modules (via libgit2), constructs an in‐memory graph representation, compiles to LLVM IR, links in a small C runtime, and can run or JIT modules.

##### File‐Structure Analysis
- Top‐level CMakeLists.txt orchestrates build of subprojects:
- chi/ : CLI front end (compile.cpp, run.cpp, get.cpp, interpret.cpp, etc.)
- lib/
– core/ : core APIs (Context, ChiModule, GraphFunction, FunctionCompiler…)
– debugger/ : Debugger API & implementation
– fetcher/ : Module fetching & caching (libgit2)
– runtime/ : C runtime to support generated code
– support/ : utility helpers (ExecutablePath, Subprocess, UUID, JSON)
- examples/ : sample code using libchigraph
- test/ : unit tests (Catch)
- third_party/ : vendored Catch
- doc/ : Doxygen, build instructions, screenshots

##### README Insights
- Describes three high‐level components: chi CLI, libchigraph, libchigraphdebugger
- Lists tech stack: LLVM/Clang for codegen, libgit2 for fetch, Boost for filesystem/args/UUID, Catch for tests

– chi CLI
– libchigraph core library
- Context & ModuleLoader
- Graph representation
- Codegen (FunctionCompiler, NodeCompiler)
– libchigraphdebugger
– fetcher module (libgit2 + ModuleCache)
– support utilities (filesystem, JSON, subprocess)
– runtime (C‐based arc.c / main.c)
– LLVM/Clang backend
– External: remote Git servers, local filesystem
1. chi CLI → Context.loadModule() → fetcher
2. fetcher → Git remote over HTTPS → local ModuleCache
3. Context parses module files → builds GraphModule → GraphFunction
4. Codegen components → generate LLVM IR
5. LLVM API → optimize & compile to machine code
6. Link in runtime C objects → final executable or JIT
7. Debugger lib hooks into Context & Graph to provide breakpoints
c. Architectural Patterns
– Layered: CLI layer, library API layer, codegen layer, backend layer
– Plugin‐like: modules fetched dynamically, cached
– Separation of concerns: fetching vs parsing vs codegen vs runtime vs debugging
d. Key Technologies/Frameworks
– CMake for build orchestration
– LLVM/Clang libraries (llvm::Module)
– libgit2 for remote module fetching
– Boost (filesystem, program_options, uuid, etc.)
– Catch for unit tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    chiCLI["chi CLI"]:::user
    click chiCLI "https://github.com/chigraph/chigraph/blob/master/chi/CMakeLists.txt"
    chiMain["main.cpp"]:::user
    click chiMain "https://github.com/chigraph/chigraph/blob/master/chi/main.cpp"
    chiCompile["compile.cpp"]:::user
    click chiCompile "https://github.com/chigraph/chigraph/blob/master/chi/compile.cpp"
    chiRun["run.cpp"]:::user
    click chiRun "https://github.com/chigraph/chigraph/blob/master/chi/run.cpp"
    chiGet["get.cpp"]:::user
    click chiGet "https://github.com/chigraph/chigraph/blob/master/chi/get.cpp"
    chiInterpret["interpret.cpp"]:::user
    click chiInterpret "https://github.com/chigraph/chigraph/blob/master/chi/interpret.cpp"
    chiInit["init.cpp"]:::user
    click chiInit "https://github.com/chigraph/chigraph/blob/master/chi/init.cpp"
    chiGetNop["get_nop.cpp"]:::user
    click chiGetNop "https://github.com/chigraph/chigraph/blob/master/chi/get_nop.cpp"

    chiCLI --> chiMain
    chiMain --> chiCompile
    chiMain --> chiRun
    chiMain --> chiGet
    chiMain --> chiInterpret
    chiMain --> chiInit
    chiMain --> chiGetNop

    chiCLI -->|"Context.loadModule()"| core

    %% Library Layer
    subgraph "Library Layer"
        core["libchigraph core library"]:::lib
        click core "https://github.com/chigraph/chigraph/blob/master/lib/core/CMakeLists.txt"
        fetcher["fetcher (libgit2 + ModuleCache)"]:::lib
        click fetcher "https://github.com/chigraph/chigraph/blob/master/lib/fetcher/CMakeLists.txt"
        debugger["libchigraphdebugger"]:::lib
        click debugger "https://github.com/chigraph/chigraph/blob/master/lib/debugger/CMakeLists.txt"
        support["support utilities"]:::lib
        click support "https://github.com/chigraph/chigraph/blob/master/lib/support/CMakeLists.txt"
        runtime["C runtime"]:::lib
        click runtime "https://github.com/chigraph/chigraph/blob/master/lib/runtime/CMakeLists.txt"
    end

    core -->|"uses support JSON, Subprocess, UUID"| support
    core -->|"loadModule calls"| fetcher
    fetcher -->|"git clone / fetch"| git
    fetcher -->|"cache modules"| localFS
    core -->|"build GraphModule/GraphFunction"| coreGraph["GraphModule & GraphFunction"]:::lib
    coreGraph --> core
    core -->|"generateIR() (FunctionCompiler, NodeCompiler)"| codegen["Codegen"]:::lib
    codegen --> core

    core -->|"Debugger hooks"| debugger
    debugger --> core

    core -->|"link runtime objects"| runtime
    runtime --> core

    core -->|"invoke LLVM API"| llvm
    codegen -->|"emit LLVM IR"| llvm

    %% Backend Layer
    llvm["LLVM/Clang backend"]:::external

    llvm -->|"optimize & compile"| machineCode["Machine Code"]:::external
    machineCode --> finalExec["Final Executable / JIT"]:::external

    %% External
    git["Remote Git Server"]:::external
    localFS["Local Filesystem / ModuleCache"]:::external

    %% Styles
    classDef user fill:#9f6,stroke:#333,stroke-width:1px;
    classDef lib fill:#6cf,stroke:#333,stroke-width:1px;
    classDef external fill:#f96,stroke:#333,stroke-width:1px;
```
