# cactus-compute/cactus architecture

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

- Interactive diagram: https://gitdiagram.com/cactus-compute/cactus
- Repository: https://github.com/cactus-compute/cactus

## Overview

##### Project type and purpose
- Cactus is an open-source, multi-platform AI inference framework. At its heart is a high-performance C/C++ library (the “cactus” folder) that implements model loading and inference via GGML backends. Around it are language bindings and plugins for Flutter (Dart), React-Native (TypeScript), native iOS, and Android (JNI). There are also example apps (C++, Flutter, React), documentation, and build scripts.

##### File structure
- Top-level:
- cactus/           — the C/C++ core library + GGML backends + patches + tools
- cactus-flutter/   — Dart/Flutter plugin (lib/, android/, ios/, ffigen.yaml)
- cactus-react/     — React-Native plugin (src/, android/, ios/, podspec, TS configs)
- cactus-ios/       — prebuilt iOS xcframework target
- examples/         — demo apps for C++, Flutter, React
- docs/             — markdown docs for each platform
- scripts/          — build and packaging scripts (shell)
- Patterns:
- Core library built via CMake → outputs static / shared libs and xcframework/JNILibs
- Language layers use FFI (Dart ffi, React-Native JSI/bridging) to call C++
- Example apps import the plugin packages and invoke APIs

##### Insights from the README
- Purpose: run LLMs locally on mobile with low overhead
- Components mentioned: CactusContext, CactusCompletionParams, initLlama, common_params
- Dependencies: GGML, CMake, Flutter SDK, React-Native CLI, CocoaPods, Android NDK

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        examples_cpp["C++ CLI Example"]:::ui
        examples_flutter["Flutter App Example"]:::ui
        examples_react["React App Example"]:::ui
    end

    %% Binding Layer
    subgraph "Binding Layer"
        flutter_plugin["Flutter Plugin (Dart ffi)"]:::binding
        react_plugin["React-Native Plugin (TS/JSI)"]:::binding
        ios_plugin["iOS Plugin (xcframework)"]:::binding
        android_jni["Android JNI Libraries"]:::binding
    end

    %% Native Core Layer
    subgraph "Native Core"
        core["C++ Core Library"]:::core
        ggml_cpu["GGML CPU Backend"]:::core
        ggml_metal["GGML Metal Backend"]:::core
        cmake["CMakeLists.txt"]:::tools
        scripts["Build Scripts"]:::tools
        xcframework["iOS CMake Project"]:::tools
    end

    %% Hardware Layer
    subgraph "Hardware"
        CPU["CPU SIMD"]:::hw
        GPU["GPU / Metal"]:::hw
    end

    %% File System
    Models["Model Files (.gguf)"]:::hw

    %% Documentation and Root
    docs["Documentation"]:::docs
    readme["README.md"]:::docs

    %% Connections: UI to Binding / Core
    examples_cpp -->|"calls API"| core
    examples_flutter -->|"uses Plugin API"| flutter_plugin
    examples_react -->|"uses Plugin API"| react_plugin

    %% Binding to Core
    flutter_plugin -->|"FFI bridge"| core
    react_plugin -->|"JSI bridge"| core
    ios_plugin -->|"XCFramework linking"| core
    android_jni -->|"JNI linking"| core

    %% Core internals
    core -->|"uses"| ggml_cpu
    core -->|"uses"| ggml_metal

    %% Backends to hardware
    ggml_cpu -->|"executes on"| CPU
    ggml_metal -->|"executes on"| GPU

    %% Build flow
    scripts -->|"invoke"| cmake
    cmake -->|"builds"| core
    cmake -->|"packages"| xcframework
    cmake -->|"outputs"| android_jni

    %% Model load
    examples_cpp -->|"loads models"| Models
    examples_flutter -->|"loads models"| Models
    examples_react -->|"loads models"| Models

    %% Docs and readme
    docs --> readme

    %% Click Events
    click core "https://github.com/cactus-compute/cactus/tree/main/cactus/"
    click ggml_cpu "https://github.com/cactus-compute/cactus/tree/main/cactus/ggml-cpu/"
    click ggml_metal "https://github.com/cactus-compute/cactus/blob/main/cactus/ggml-metal.h"
    click ggml_metal "https://github.com/cactus-compute/cactus/blob/main/cactus/ggml-metal.m"
    click cmake "https://github.com/cactus-compute/cactus/blob/main/cactus/CMakeLists.txt"
    click scripts "https://github.com/cactus-compute/cactus/tree/main/scripts/"
    click xcframework "https://github.com/cactus-compute/cactus/tree/main/cactus-ios/cactus.xcframework/"
    click android_jni "https://github.com/cactus-compute/cactus/blob/main/cactus-flutter/android/jniLibs.zip"
    click flutter_plugin "https://github.com/cactus-compute/cactus/tree/main/cactus-flutter/lib/"
    click react_plugin "https://github.com/cactus-compute/cactus/tree/main/cactus-react/src/"
    click examples_cpp "https://github.com/cactus-compute/cactus/tree/main/examples/cpp/"
    click examples_flutter "https://github.com/cactus-compute/cactus/tree/main/examples/flutter/"
    click examples_react "https://github.com/cactus-compute/cactus/tree/main/examples/react/"
    click docs "https://github.com/cactus-compute/cactus/tree/main/docs/"
    click readme "https://github.com/cactus-compute/cactus/blob/main/README.md"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#90CAF9;
    classDef binding fill:#C8E6C9,stroke:#66BB6A;
    classDef core fill:#FFE0B2,stroke:#FFA726;
    classDef hw fill:#CFD8DC,stroke:#90A4AE;
    classDef tools fill:#E1BEE7,stroke:#AB47BC;
    classDef docs fill:#F0F4C3,stroke:#DCE775;
```
