# railwayapp/railpack architecture

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

- Interactive diagram: https://gitdiagram.com/railwayapp/railpack
- Repository: https://github.com/railwayapp/railpack

## Overview

##### Main Components
- CLI Frontend (cmd/cli): the user‑facing binary (railpack) that parses commands, loads configuration (mise.toml), and dispatches build actions.
- Core Engine (core/…): orchestrates detection, build‑plan generation, templating, and logging. Key sub‑modules:
– Resolver: detects project language & versions.
– Generate: builds an abstract BuildPlan (steps, layers, commands).
– Plan: defines step ordering, caching, filters.
– Providers: language‑specific logic (node, python, java, etc.) plugged into Generate & Plan.
- BuildKit Interface (buildkit/…): translates the abstract BuildPlan into a BuildKit LLB (low‑level build) graph and executes it, producing image layers.
- Images & Docker Integration: Dockerfiles directory, local Docker daemon (or remote registry) for final image build/push.
- Docs Site (docs/…): an Astro/React static site that serves as user documentation (separate deployment).
- CI/CD & Releases (.github/, goreleaser.yml, Dockerfiles/): pipelines that test, build, package, and release binaries and Docker images.

##### Relationships & Data Flow
- User invokes railpack CLI → CLI Frontend
→ reads mise.toml / command‑line flags
→ calls Core Engine (Resolver → Generate → Plan)
→ passes BuildPlan to BuildKit Interface
→ BuildKit Interface constructs LLB graph, communicates with BuildKit daemon
→ Docker daemon builds image layers → final image pushed to registry or saved locally
- Providers plug into Core Engine: each language/provider module registers detection rules and build‑step builders.
- Docs Site is built & deployed separately (Astro → static assets → hosting).
- CI workflows run tests against Core, BuildKit, CLI, integration tests, and deploy releases via GoReleaser and Dockerfiles.

##### Architectural Patterns
- Plugin‑style providers: Core’s Generate & Plan modules load language‑specific “providers” for extensibility.
- Graph‑based build: abstract BuildPlan → directed acyclic graph (DAG) → LLB graph → container image layers.
- Layer‑caching & parallel steps via BuildKit.
- Separation of concerns: CLI (presentation), Core (business logic), BuildKit (execution engine).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User interaction
    UserTerminal["User Terminal"]:::external
    UserTerminal -->|"invokes CLI"| CLI

    %% Railpack Components
    CLI["CLI Frontend"]:::railpack
    click CLI "https://github.com/railwayapp/railpack/blob/main/cmd/cli/main.go"
    CLI -->|"reads mise.toml & flags"| Core

    Core["Core Engine"]:::railpack
    click Core "https://github.com/railwayapp/railpack/blob/main/core/core.go"
    Core -->|"pass BuildPlan (JSON)"| BuildKit

    BuildKit["BuildKit Interface"]:::railpack
    click BuildKit "https://github.com/railwayapp/railpack/blob/main/buildkit/build.go"
    BuildKit -->|"LLB Graph"| DockerDaemon

    DockerDaemon["Docker Daemon"]:::external
    DockerDaemon -->|"builds layers"| Registry

    Registry["Container Registry"]:::external

    %% Core internals
    subgraph "Core Engine"
        direction TB
        Resolver["Resolver"]:::railpack
        click Resolver "https://github.com/railwayapp/railpack/blob/main/core/resolver/resolver.go"
        Generate["Generate"]:::railpack
        click Generate "https://github.com/railwayapp/railpack/blob/main/core/generate/context.go"
        Plan["Plan"]:::railpack
        click Plan "https://github.com/railwayapp/railpack/blob/main/core/plan/plan.go"
        Resolver -->|detects language| Generate
        Generate -->|abstract plan| Plan
    end

    %% Providers plugins
    subgraph "Providers"
        Providers["Providers"]:::providers
        click Providers "https://github.com/railwayapp/railpack/blob/main/core/providers/provider.go"
    end
    Providers -.->|plugin registration| Generate
    Providers -.->|plugin registration| Plan

    %% Documentation Site
    Docs["Docs Site"]:::docs
    click Docs "https://github.com/railwayapp/railpack/blob/main/docs/astro.config.mjs"

    %% CI/CD Pipelines
    CI["CI/CD Pipelines"]:::ci_cd
    click CI "https://github.com/railwayapp/railpack/blob/main/.github/workflows/ci.yml"
    CI -.->|build & test| CLI
    CI -.->|deploy docs| Docs

    %% Styles
    classDef railpack fill:#D0E7FF,stroke:#0366D6,color:#0366D6;
    classDef providers fill:#DFF3D7,stroke:#28A745,color:#1E4620,stroke-dasharray: 5 5;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef docs fill:#FEF3C7,stroke:#D69D00,color:#8A6B00;
    classDef ci_cd fill:#FEF3C7,stroke:#D69D00,color:#8A6B00;
```
