# 0ndt/vectorscan-rs architecture

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

- Interactive diagram: https://gitdiagram.com/0ndt/vectorscan-rs
- Repository: https://github.com/0ndt/vectorscan-rs

## Overview

##### Project Type and Purpose
- This is a Rust “sys”-style crate plus a safe wrapper (vectorscan-rs) that bundles, builds, and links a vendored copy of the Vectorscan (Hyperscan fork) C/C++ library.
- It exposes minimal FFI bindings from Vectorscan’s block-based regex matching API into Rust, via bindgen when requested.

##### High-Level Architecture
- Front-end: Rust crate (Cargo, src/lib.rs, src/bindings.rs)
- Build system: build.rs (Rust build script) + CMake (in vectorscan-sys)
- Vendored C/C++ sources: vectorscan-sys/…
- External tools/dependencies: CMake, Clang (for bindgen), bindgen, Docker (optional)

##### Main Components & Relationships
[Developer]
↓ invokes
[Cargo Build]
↓ runs
[build.rs]
├─(1) spawns CMake → compiles vectorscan-sys sources → produces libvectorscan.a / .so
└─(2, if “gen” feature) calls bindgen (Clang) on hs.h → generates src/bindings.rs
↓ then
[Rust Compiler]
compiles src/lib.rs + bindings.rs → links against libvectorscan
↓ outputs
[vectorscan-rs Crate]

##### Detailed Components
- Rust Layer
- Cargo.toml – crate metadata, features (e.g., “gen”)
- build.rs – orchestrates CMake and bindgen
- src/bindings.rs – raw unsafe FFI signatures (auto-generated)
- src/lib.rs – safe wrapper functions/types around FFI
- Vendored Layer (vectorscan-sys)
- CMakeLists.txt + cmake/… – cross-platform build
- src/… – hundreds of C/C++ source files implementing regex engines (chimera, fdr, nfa, rose, etc.)
- /… – headers for public API
- tools/, examples/, unit/… – benchmarks, tests, fuzzers (disabled by default)
- External Tools
- CMake – configure & build the C/C++ library
- Clang & bindgen – generate Rust FFI bindings when “gen” is enabled

##### Key Interactions & Data Flow
- Cargo → build.rs: “Run build script”
- build.rs → CMake: “Configure & build vendored library”
- build.rs → bindgen (optional): “Parse hs.h → emit Rust declarations”
- Rust code → libvectorscan.a: “Link FFI”
- Rust public API → application code: “Call regex matching functions”

##### Architectural Patterns & Principles
- Layered Build: Rust layer on top, build layer in middle, C/C++ layer at bottom
- FFI Boundary: clearly separated via bindings.rs and lib.rs
- Feature-gated code generation (bindgen)
- Vendoring: avoids external C/C++ version drift
- Build-time code gen and linking

- C/C++ components (vectorscan-sys, CMake) in another
- External tools (bindgen, Clang, Docker) in a third

##### Essential Elements
- Clear labels for: Cargo, build.rs, CMake (vectorscan-sys), bindgen, src/lib.rs, src/bindings.rs, libvectorscan.a

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Rust Layer"
        Cargo["Cargo"]:::rust
        buildRS["build.rs"]:::rust
        Bindings["src/bindings.rs"]:::rust
        Lib["src/lib.rs"]:::rust
    end

    subgraph "Vendored C/C++ Layer"
        CMakeLists["CMakeLists.txt"]:::cpp
        CMakeModules["cmake/"]:::cpp
        Headers["include/"]:::cpp
        CppSrc["src/"]:::cpp
        WrapperH["wrapper.h"]:::cpp
    end

    subgraph "External Tools"
        CMake["CMake"]:::tool
        BindgenTool["bindgen"]:::tool
        Clang["Clang"]:::tool
        Docker["Docker"]:::tool
    end

    Developer["Developer"]:::external
    RustCompiler["Rust Compiler"]:::rust
    LibArchive(("libvectorscan.a/.so")):::cpp
    Crate(("vectorscan-rs Crate")):::rust

    Developer -->|"invokes"| Cargo
    Cargo -->|"runs build.rs"| buildRS
    buildRS -->|"configure & build"| CMake
    CMake -->|"reads"| CMakeLists
    CMake -->|"reads"| CMakeModules
    CMake -->|"reads"| Headers
    CMake -->|"reads"| CppSrc
    CMake -->|"reads"| WrapperH
    CMake -->|"builds"| LibArchive
    buildRS -->|"if gen feature generate"| BindgenTool
    BindgenTool -->|"calls Clang"| Clang
    BindgenTool -->|"parse hs.h → emit Rust declarations"| Bindings
    buildRS -->|"then hands off to"| RustCompiler
    RustCompiler -->|"compile src/lib.rs & bindings"| Lib
    RustCompiler -->|"links against"| LibArchive
    RustCompiler -->|"outputs"| Crate

    click Cargo "https://github.com/0ndt/vectorscan-rs/blob/master/Cargo.toml"
    click buildRS "https://github.com/0ndt/vectorscan-rs/blob/master/build.rs"
    click Bindings "https://github.com/0ndt/vectorscan-rs/blob/master/src/bindings.rs"
    click Lib "https://github.com/0ndt/vectorscan-rs/blob/master/src/lib.rs"
    click CMakeLists "https://github.com/0ndt/vectorscan-rs/blob/master/vectorscan-sys/CMakeLists.txt"
    click CMakeModules "https://github.com/0ndt/vectorscan-rs/tree/master/vectorscan-sys/cmake/"
    click Headers "https://github.com/0ndt/vectorscan-rs/tree/master/vectorscan-sys/include/"
    click CppSrc "https://github.com/0ndt/vectorscan-rs/tree/master/vectorscan-sys/src/"
    click WrapperH "https://github.com/0ndt/vectorscan-rs/blob/master/wrapper.h"

    classDef rust fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef cpp fill:#FADBD8,stroke:#7B241C,color:#512E5F
    classDef tool fill:#D5F5E3,stroke:#1D8348,color:#145A32
    classDef external fill:#E8DAEF,stroke:#6C3483,color:#4A235A
```
