# paketo-buildpacks/libpak architecture

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

- Interactive diagram: https://gitdiagram.com/paketo-buildpacks/libpak
- Repository: https://github.com/paketo-buildpacks/libpak

## Overview

##### Project type and purpose
- Type: Go library (module) intended to be imported by Paketo buildpacks.
- Purpose: Provide reusable functionality—detect/build/generate phases, dependency resolution, layer management, file operations, SBOM generation, logging—for Paketo-style buildpacks.

##### File structure
- Top-level API files:
– main.go (entry)
– detect.go (detect phase)
– build.go, generate.go (build + generate phases)
– resolve.go, buildmodule.go, buildpack_plan.go (supporting build-time logic)
- Core packages:
– bindings/ : bind environment/platform info
– dependency* : resolve and cache external dependencies
– crush/ : extract/compress archives
– effect/ : wrap OS process execution
– sbom/ : generate Software Bill of Materials
– sherpa/ : filesystem ops (copy, exists, env var)
– log/ : structured logging
– utils/ : TOML writers, exit handlers, entry & environment writers
- Tests and mocks confirm module responsibilities.

##### README for additional insights
- README confirms: “Go library with useful functionality for building Paketo-style buildpacks.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    BPAuthor["Buildpack Author Code"]:::external
    Paketo["Paketo Lifecycle"]:::external
    Platform["Platform / FileSystem"]:::external

    %% Core API
    subgraph "Core API"
        MainEntrypoint["main.go"]:::core
        DetectAPI["Detect()\\ndetect.go"]:::core
        BuildAPI["Build()\\nbuild.go"]:::core
        GenerateAPI["Generate()\\ngenerate.go"]:::core
    end

    %% Submodules
    subgraph "Submodules"
        subgraph "bindings"
            BindResolve["resolve.go"]:::binding
        end
        subgraph "dependency resolution"
            DepRes["dependency.go"]:::submodule
            DepCache["dependency_cache.go"]:::submodule
        end
        subgraph "buildpack plan & buildmodule"
            BuildPlan["buildpack_plan.go"]:::submodule
            BuildModule["buildmodule.go"]:::submodule
        end
        subgraph "crush (archive ops)"
            Crush["crush.go"]:::io
        end
        subgraph "effect (process executor)"
            Exec["executor.go"]:::process
            ExecUnix["executor_unix.go"]:::process
            ExecWin["executor_windows.go"]:::process
        end
        subgraph "sherpa (filesystem ops)"
            SherpaMain["sherpa.go"]:::io
            CopyDir["copy_dir.go"]:::io
            CopyFile["copy_file.go"]:::io
            Exists["exists.go"]:::io
            EnvVarOp["env_var.go"]:::io
            FileListing["file_listing.go"]:::io
            Nodejs["nodejs.go"]:::io
        end
        subgraph "sbom"
            SBOM["sbom.go"]:::sbom
        end
        subgraph "log"
            Logger["logger.go"]:::log
            Formatter["formatter.go"]:::log
            WriterLog["writer.go"]:::log
        end
        subgraph "utils"
            TomlWriter["toml_writer.go"]:::util
            TomlMarshal["toml_marshal.go"]:::util
            EntryWriter["entry_writer.go"]:::util
            EnvWriter["environment_writer.go"]:::util
            ExitHandler["exit_handler.go"]:::util
        end
    end

    %% Relationships
    BPAuthor --> Paketo
    Paketo -->|"invokes"| MainEntrypoint
    MainEntrypoint --> DetectAPI
    MainEntrypoint --> BuildAPI
    MainEntrypoint --> GenerateAPI

    DetectAPI --> BindResolve
    DetectAPI --> Logger
    DetectAPI --> Formatter
    DetectAPI --> WriterLog

    BuildAPI --> DepRes
    BuildAPI --> DepCache
    BuildAPI --> BuildPlan
    BuildAPI --> BuildModule
    BuildAPI --> Crush
    BuildAPI --> Exec
    BuildAPI --> ExecUnix
    BuildAPI --> ExecWin
    BuildAPI --> SherpaMain
    BuildAPI --> CopyDir
    BuildAPI --> CopyFile
    BuildAPI --> Exists
    BuildAPI --> EnvVarOp
    BuildAPI --> FileListing
    BuildAPI --> Nodejs
    BuildAPI --> SBOM
    BuildAPI --> Logger
    BuildAPI --> Formatter
    BuildAPI --> WriterLog
    BuildAPI --> TomlWriter
    BuildAPI --> TomlMarshal
    BuildAPI --> EntryWriter
    BuildAPI --> EnvWriter
    BuildAPI --> ExitHandler

    GenerateAPI --> SherpaMain
    GenerateAPI --> EntryWriter
    GenerateAPI --> EnvWriter
    GenerateAPI --> Logger
    GenerateAPI --> Formatter
    GenerateAPI --> WriterLog

    BindResolve --> Platform
    SherpaMain --> Platform
    CopyDir --> Platform
    CopyFile --> Platform
    EnvVarOp --> Platform
    EntryWriter --> Platform
    EnvWriter --> Platform
    SBOM --> Platform

    DepRes --> TomlWriter
    DepCache --> TomlWriter
    BuildPlan --> TomlMarshal
    BuildModule --> TomlMarshal

    %% Click Events
    click MainEntrypoint "https://github.com/paketo-buildpacks/libpak/blob/main/main.go"
    click DetectAPI "https://github.com/paketo-buildpacks/libpak/blob/main/detect.go"
    click BuildAPI "https://github.com/paketo-buildpacks/libpak/blob/main/build.go"
    click GenerateAPI "https://github.com/paketo-buildpacks/libpak/blob/main/generate.go"
    click BindResolve "https://github.com/paketo-buildpacks/libpak/blob/main/bindings/resolve.go"
    click DepRes "https://github.com/paketo-buildpacks/libpak/blob/main/dependency.go"
    click DepCache "https://github.com/paketo-buildpacks/libpak/blob/main/dependency_cache.go"
    click BuildPlan "https://github.com/paketo-buildpacks/libpak/blob/main/buildpack_plan.go"
    click BuildModule "https://github.com/paketo-buildpacks/libpak/blob/main/buildmodule.go"
    click Crush "https://github.com/paketo-buildpacks/libpak/blob/main/crush/crush.go"
    click Exec "https://github.com/paketo-buildpacks/libpak/blob/main/effect/executor.go"
    click ExecUnix "https://github.com/paketo-buildpacks/libpak/blob/main/effect/executor_unix.go"
    click ExecWin "https://github.com/paketo-buildpacks/libpak/blob/main/effect/executor_windows.go"
    click SherpaMain "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/sherpa.go"
    click CopyDir "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/copy_dir.go"
    click CopyFile "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/copy_file.go"
    click Exists "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/exists.go"
    click EnvVarOp "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/env_var.go"
    click FileListing "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/file_listing.go"
    click Nodejs "https://github.com/paketo-buildpacks/libpak/blob/main/sherpa/nodejs.go"
    click SBOM "https://github.com/paketo-buildpacks/libpak/blob/main/sbom/sbom.go"
    click Logger "https://github.com/paketo-buildpacks/libpak/blob/main/log/logger.go"
    click Formatter "https://github.com/paketo-buildpacks/libpak/blob/main/log/formatter.go"
    click WriterLog "https://github.com/paketo-buildpacks/libpak/blob/main/log/writer.go"
    click TomlWriter "https://github.com/paketo-buildpacks/libpak/blob/main/utils/toml_writer.go"
    click TomlMarshal "https://github.com/paketo-buildpacks/libpak/blob/main/utils/toml_marshal.go"
    click EntryWriter "https://github.com/paketo-buildpacks/libpak/blob/main/utils/entry_writer.go"
    click EnvWriter "https://github.com/paketo-buildpacks/libpak/blob/main/utils/environment_writer.go"
    click ExitHandler "https://github.com/paketo-buildpacks/libpak/blob/main/utils/exit_handler.go"

    %% Styles
    classDef external fill:#fee,stroke:#933,stroke-width:2px
    classDef core fill:#bbf,stroke:#339,stroke-width:2px
    classDef binding fill:#bfb,stroke:#383,stroke-width:2px
    classDef submodule fill:#dfd,stroke:#393,stroke-width:1px
    classDef io fill:#ffd,stroke:#993,stroke-width:1px
    classDef process fill:#fdc,stroke:#963,stroke-width:1px
    classDef sbom fill:#fdf,stroke:#939,stroke-width:1px
    classDef log fill:#ddf,stroke:#339,stroke-width:1px
    classDef util fill:#fbb,stroke:#933,stroke-width:1px
```
