# buildpacks/libcnb architecture

> Architecture diagram of the GitHub repository buildpacks/libcnb, 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/buildpacks/libcnb
- Repository: https://github.com/buildpacks/libcnb

## Overview

##### Project Type and Purpose
- This is a Go language binding (a library) for the Cloud Native Buildpacks (CNB) API.
- It exposes a non-opinionated Go API to:
- Detect whether a buildpack applies (“detect”)
- Execute buildpack logic and produce layers (“build”)
- Generate project artifacts (“generate”)
- It is consumed by tools like `pack` or any Go program that wants to orchestrate CNB buildpacks.

##### High-Level Architecture
- External Consumer (e.g., the `pack` CLI or another Go program)
→ imports `github.com/buildpacks/libcnb`
→ calls top-level functions: Detect(), Build(), Generate()
- Public API Layer (root package)
- main.go → entrypoint for CLI or Go programs
- detect.go, build.go, generate.go → core workflows
- config.go, environment.go, extension.go, process.go, store.go, layer.go, platform.go → domain constructs
- Internal Utility Layer (`internal/`)
- config_map.go, directory_contents.go → inspect file system
- toml_writer.go, execd_writer.go, environment_writer.go → write CNB metadata (TOML, exec.d scripts, env files)
- exit_handler.go, formatter.go → handle process exit codes & logging format
- match_toml.go → parse and match buildpack.toml
- Logging Subsystem (`log/`)
- logger.go → structured logger interface
- formatter.go → log formatting
- Supporting Artifacts
- `examples/` → usage examples
- `mocks/` & `log/mocks/` → test doubles for unit tests
- `tools/` → small helper binaries
- `testdata/` → sample JSON, TOML for tests

##### Relationships and Data Flow
- Consumer invokes Detect()
→ Detect() uses MatchTOML → ConfigMap → DirectoryContents → returns a Plan
- Consumer invokes Build()
→ Build() reads Platform API, Environment, Layer definitions
→ uses ExecDWriter, EnvWriter, TOMLWriter to produce output artifacts
- Consumer invokes Generate()
→ Generate() orchestrates metadata output for builders, extensions
- All components emit logs via the Logger interface

##### Architectural Patterns & Principles
- Package encapsulation: only root package is public; everything under `internal/` is private.
- Separation of concerns:
- Public API deals in CNB concepts (buildpacks, layers, plans)
- Internal packages deal with on-disk representation and formatting
- Dependency Injection via interfaces (e.g., logger, file-writers) for testability
- Clear distinction between domain constructs and I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "External Consumer"
    ext["External Consumer\n(main.go)"]:::external
  end

  subgraph "Public API Layer"
    detect["Detect()\n(detect.go)"]:::public
    build["Build()\n(build.go)"]:::public
    generate["Generate()\n(generate.go)"]:::public
    config["Config\n(config.go)"]:::public
    environment["Environment\n(environment.go)"]:::public
    extension["Extension\n(extension.go)"]:::public
    process["Process\n(process.go)"]:::public
    store["Store\n(store.go)"]:::public
    layer["Layer\n(layer.go)"]:::public
    platform["Platform\n(platform.go)"]:::public
  end

  subgraph "Internal Utilities"
    match["MatchTOML\n(internal/match_toml.go)"]:::internal
    configMap["ConfigMap\n(internal/config_map.go)"]:::internal
    dirContents["DirectoryContents\n(internal/directory_contents.go)"]:::internal
    tomlWriter["TOMLWriter\n(internal/toml_writer.go)"]:::internal
    execdWriter["ExecDWriter\n(internal/execd_writer.go)"]:::internal
    envWriter["EnvWriter\n(internal/environment_writer.go)"]:::internal
    exitHandler["ExitHandler\n(internal/exit_handler.go)"]:::internal
    formatterI["Formatter\n(internal/formatter.go)"]:::internal
  end

  subgraph "Logging Subsystem"
    logger["Logger Interface\n(log/logger.go)"]:::logging
    logFormatter["Formatter\n(log/formatter.go)"]:::logging
  end

  subgraph "Supporting Artifacts"
    examples["Examples\n(examples/)"]:::support
    mocks["Mocks\n(mocks/)"]:::support
    logMocks["Log Mocks\n(log/mocks/)"]:::support
    testdata["Testdata\n(testdata/)"]:::support
    tools["Tools\n(tools/)"]:::support
  end

  ext -->|imports & calls| detect
  ext -->|imports & calls| build
  ext -->|imports & calls| generate

  detect -->|uses| match
  match -->|uses| configMap
  configMap -->|uses| dirContents

  build -->|reads| platform
  build -->|reads| environment
  build -->|reads| layer
  build -->|writes| execdWriter
  build -->|writes| envWriter
  build -->|writes| tomlWriter

  generate -->|orchestrates| tomlWriter

  %% Logging relationships
  detect -->|logs via| logger
  build -->|logs via| logger
  generate -->|logs via| logger
  match -->|logs via| logger
  configMap -->|logs via| logger
  tomlWriter -->|logs via| logger
  execdWriter -->|logs via| logger
  envWriter -->|logs via| logger
  exitHandler -->|logs via| logger
  formatterI -->|logs via| logger
  logger --> logFormatter

  %% Click Events
  click ext "https://github.com/buildpacks/libcnb/blob/main/main.go"
  click detect "https://github.com/buildpacks/libcnb/blob/main/detect.go"
  click build "https://github.com/buildpacks/libcnb/blob/main/build.go"
  click generate "https://github.com/buildpacks/libcnb/blob/main/generate.go"
  click config "https://github.com/buildpacks/libcnb/blob/main/config.go"
  click environment "https://github.com/buildpacks/libcnb/blob/main/environment.go"
  click extension "https://github.com/buildpacks/libcnb/blob/main/extension.go"
  click process "https://github.com/buildpacks/libcnb/blob/main/process.go"
  click store "https://github.com/buildpacks/libcnb/blob/main/store.go"
  click layer "https://github.com/buildpacks/libcnb/blob/main/layer.go"
  click platform "https://github.com/buildpacks/libcnb/blob/main/platform.go"
  click match "https://github.com/buildpacks/libcnb/blob/main/internal/match_toml.go"
  click configMap "https://github.com/buildpacks/libcnb/blob/main/internal/config_map.go"
  click dirContents "https://github.com/buildpacks/libcnb/blob/main/internal/directory_contents.go"
  click tomlWriter "https://github.com/buildpacks/libcnb/blob/main/internal/toml_writer.go"
  click execdWriter "https://github.com/buildpacks/libcnb/blob/main/internal/execd_writer.go"
  click envWriter "https://github.com/buildpacks/libcnb/blob/main/internal/environment_writer.go"
  click exitHandler "https://github.com/buildpacks/libcnb/blob/main/internal/exit_handler.go"
  click formatterI "https://github.com/buildpacks/libcnb/blob/main/internal/formatter.go"
  click logger "https://github.com/buildpacks/libcnb/blob/main/log/logger.go"
  click logFormatter "https://github.com/buildpacks/libcnb/blob/main/log/formatter.go"
  click examples "https://github.com/buildpacks/libcnb/tree/main/examples/"
  click mocks "https://github.com/buildpacks/libcnb/tree/main/mocks/"
  click logMocks "https://github.com/buildpacks/libcnb/tree/main/log/mocks/"
  click testdata "https://github.com/buildpacks/libcnb/tree/main/testdata/"
  click tools "https://github.com/buildpacks/libcnb/tree/main/tools/"

  classDef public fill:#D0E1FF,stroke:#0000FF,color:#0000FF
  classDef internal fill:#F0F0F0,stroke:#AAAAAA,color:#777777
  classDef external fill:#DFFFE0,stroke:#00AA00,color:#00AA00
  classDef logging fill:#FFF5CC,stroke:#FFC000,color:#C09000
  classDef support fill:#E0E0E0,stroke:#888888,color:#555555
```
