# wasilibs/go-re2 architecture

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

- Interactive diagram: https://gitdiagram.com/wasilibs/go-re2
- Repository: https://github.com/wasilibs/go-re2

## Overview

##### Main Components

a) Core Components:
- Regular Expression Engine Interface (re2.go)
- WebAssembly Implementation Layer
- CGO Implementation Layer
- Internal RE2 Bridge Components

b) Integration Points:
- Standard Library Compatibility Layer
- WebAssembly Runtime (wazero)
- Native RE2 Library Interface

**┌─ Application Layer ─────────────────────────┐**
- (Client Code using regexp-compatible API)    │
- ┬───────────────────────┬─┘

**┌─ API Layer ───────┴───────────────────────┴─┐**
- re2.go (Public API)                         │
- ┬───────────────────────┬─┘

**┌─ Implementation ──┴───────────┐ ┌─────────┴─┐**
- WebAssembly (Default)         │ │   CGO     │
- ┌─────────────────────────┐   │ │ (Optional)│
- wazero runtime     │   │ └───────┬───┘
- ┬──────────────┘   │         │

- ┌──────────┴──────────────┐   │ ┌───────┴───┐
- re2.wasm module      │   │ │ Native RE2│
- ┘   │ │  Library  │
- ┬─┘ └───────────┘

**┌─ Internal Bridge ──────────┴─────────────────┐**
- internal/re2_wazero.go                       │
- internal/re2_re2_cgo.go                      │
- internal/cre2/                               │
- ┬──┘

**┌─ Core RE2 Engine ────────────────────────┴──┐**
- (C++ RE2 Library - Compiled to WASM/Native)  │
- ┬──┘

##### Additional Elements

- Performance characteristics notes
- Version compatibility information
- Build configuration options

##### Implementation Details to Note

- Memory management boundaries
- Thread safety considerations
- API compatibility points with stdlib

##### Optimization Notes

- RE2's special optimizations for different regex patterns
- Parallel execution paths
- Where performance gains occur for large inputs

##### Integration points with the Go ecosystem

This design captures both the architectural complexity and the performance characteristics that make go-re2 unique, especially its ability to handle complex patterns and large inputs more efficiently than the standard library.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Application Layer"
        AppCode["Client Application Code"]:::client
    end

    subgraph "API Layer"
        PublicAPI["Public RE2 API"]:::api
        click PublicAPI "https://github.com/wasilibs/go-re2/blob/main/re2.go"
    end

    subgraph "Implementation Layer"
        direction TB
        subgraph "WebAssembly Path"
            direction TB
            WasmRuntime["Wazero Runtime"]:::wasm
            WasmModule["RE2 WASM Module"]:::wasm
            WasmConfig["WASM Configuration"]:::wasm
            WasmMemory["Memory Management"]:::wasm
            
            click WasmModule "https://github.com/wasilibs/go-re2/blob/main/internal/wasm/libcre2.wasm"
            click WasmConfig "https://github.com/wasilibs/go-re2/blob/main/internal/re2_wazero_config.go"
            click WasmMemory "https://github.com/wasilibs/go-re2/blob/main/internal/wasm/memory.wasm"
        end

        subgraph "CGO Path"
            direction TB
            CGOImpl["CGO Implementation"]:::cgo
            NativeRE2["Native RE2 Library"]:::cgo
            
            click CGOImpl "https://github.com/wasilibs/go-re2/blob/main/internal/re2_re2_cgo.go"
        end
    end

    subgraph "Internal Bridge Layer"
        direction TB
        WasmBridge["RE2 Wazero Bridge"]:::bridge
        CGOBridge["RE2 CGO Bridge"]:::bridge
        CoreInterface["Core RE2 Interface"]:::bridge
        SetOps["Set Operations"]:::bridge
        
        click WasmBridge "https://github.com/wasilibs/go-re2/blob/main/internal/re2_wazero.go"
        click CGOBridge "https://github.com/wasilibs/go-re2/blob/main/internal/cre2/cre2.go"
        click CoreInterface "https://github.com/wasilibs/go-re2/blob/main/internal/re2.go"
        click SetOps "https://github.com/wasilibs/go-re2/blob/main/internal/set.go"
    end

    subgraph "Build System"
        direction TB
        BuildTools["Build Tools"]:::build
        WasmBuildTools["WASM Build Tools"]:::build
        Experimental["Experimental Features"]:::build
        
        click BuildTools "https://github.com/wasilibs/go-re2/blob/main/build/main.go"
        click WasmBuildTools "https://github.com/wasilibs/go-re2/tree/main/buildtools/wasm"
        click Experimental "https://github.com/wasilibs/go-re2/blob/main/experimental/experimental.go"
    end

    %% Connections
    AppCode --> PublicAPI
    PublicAPI --> WasmBridge
    PublicAPI -.-> CGOBridge
    
    WasmBridge --> WasmRuntime
    WasmRuntime --> WasmModule
    WasmConfig --> WasmRuntime
    WasmMemory --> WasmModule
    
    CGOBridge --> CGOImpl
    CGOImpl --> NativeRE2
    
    WasmBridge --> CoreInterface
    CGOBridge --> CoreInterface
    CoreInterface --> SetOps
    
    BuildTools --> WasmBuildTools
    WasmBuildTools --> WasmModule
    
    %% Styling
    classDef client fill:#e1f5fe,stroke:#01579b
    classDef api fill:#e8f5e9,stroke:#2e7d32
    classDef wasm fill:#fff3e0,stroke:#ef6c00
    classDef cgo fill:#fce4ec,stroke:#c2185b
    classDef bridge fill:#f3e5f5,stroke:#7b1fa2
    classDef build fill:#eceff1,stroke:#455a64

    %% Legend
    subgraph Legend
        direction TB
        Client["Client Layer"]:::client
        API["API Layer"]:::api
        WASM["WebAssembly Components"]:::wasm
        CGO["CGO Components"]:::cgo
        Bridge["Internal Bridge"]:::bridge
        Build["Build System"]:::build
    end
```
