# cshum/vipsgen architecture

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

- Interactive diagram: https://gitdiagram.com/cshum/vipsgen
- Repository: https://github.com/cshum/vipsgen

## Overview

##### Project type and purpose
- vipsgen is an open-source code‐generation tool and library written in Go.
- Its purpose is to generate type-safe, idiomatic Go bindings for the C image-processing library libvips, using GObject introspection.

##### File structure
Top-level:
- cmd/vipsgen – the CLI entry point that drives generation
- internal/
– introspection – reads GObject/C header metadata (enum, operations)
– generator – orchestrates code output by combining introspection data with templates
– templates – Go- and C-template files for codegen
– util modules for shared logic
- vips/ – the default pre-generated Go and C binding layers for libvips 8.17
- pointer/ – pointer helper utilities and tests for CGO interactions
- examples/ – sample usage of the generated vips package
- Makefile, go.mod, CI workflows, LICENSE, README.md

##### README insights
- Describes a four-layer binding architecture:
1. Go Method Layer (idiomatic methods on `*Image`)
2. Go Binding Layer (CGO wrappers that call C helpers)
3. C Layer (vipsgen_foo wrapper functions that wrap libvips variadic API)
4. libvips (the underlying C library with GObject introspection)
- Explains how the CLI (`vipsgen`) invokes GObject introspection, loads templates, and writes output into a target directory.
- Highlights dependencies: Go, CGO, pkg-config, GObject introspection support.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Developer Tools
    CLI["CLI Front-End\n(cmd/vipsgen)"]:::cli
    click CLI "https://github.com/cshum/vipsgen/tree/main/cmd/vipsgen/"

    %% Code Generation Internals
    subgraph "Code Generation Pipeline"
        direction TB
        INT["Introspection Module"]:::internals
        click INT "https://github.com/cshum/vipsgen/tree/main/internal/introspection/"
        TMP["Template Loader"]:::internals
        click TMP "https://github.com/cshum/vipsgen/tree/main/internal/templates/"
        GEN["Generator Core"]:::internals
        click GEN "https://github.com/cshum/vipsgen/tree/main/internal/generator/"
    end

    %% Generated Code Package
    subgraph "Generated vips Package" 
        direction TB
        subgraph "Go Method & Binding Layer"
            GOBIND["image.go, connection.go,\ncallback.go, vips.go,\ntypes.go, util.go"]:::generated
        end
        subgraph "C Wrapper Layer"
            CWRAP["connection.c/h,\nutil.c/h, vips.c/h"]:::generated
        end
        click GOBIND "https://github.com/cshum/vipsgen/tree/main/vips/"
        click CWRAP "https://github.com/cshum/vipsgen/tree/main/vips/"
    end

    %% Pointer Utilities
    PTR["Pointer Utilities"]:::internals
    click PTR "https://github.com/cshum/vipsgen/tree/main/pointer/"

    %% Examples
    EX["Examples"]:::generated
    click EX "https://github.com/cshum/vipsgen/tree/main/examples/"

    %% External Systems
    LIB["libvips"]:::external
    PKG["pkg-config & CGO"]:::external
    CI["CI Workflow"]:::external
    click CI "https://github.com/cshum/vipsgen/blob/main/.github/workflows/ci.yml"

    %% User Application
    APP["User Application\n(imports vips)"]:::cli

    %% Data Flow
    CLI -->|"load introspection"| INT
    CLI -->|"load templates"| TMP
    INT --> GEN
    TMP --> GEN
    GEN -->|"generate files"| GOBIND
    GEN -->|"generate files"| CWRAP

    APP -->|"calls Image.Resize"| GOBIND
    GOBIND -->|"CGO calls"| CWRAP
    CWRAP -->|"libvips API"| LIB

    PTR -->|"CGO helpers"| GOBIND

    PKG -->|"enables CGO"| CLI
    PKG -->|"enables CGO"| APP

    CI --> CLI

    EX --> APP

    %% Styles
    classDef cli fill:#bbdefb,stroke:#2196f3,color:#0d47a1
    classDef internals fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef generated fill:#fff9c4,stroke:#fbc02d,color:#f57f17
    classDef external fill:#ffebee,stroke-dasharray: 5 5,stroke:#d32f2f,color:#b71c1c
```
