# hashicorp/hcl architecture

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

- Interactive diagram: https://gitdiagram.com/hashicorp/hcl
- Repository: https://github.com/hashicorp/hcl

## Overview

HCL is a Go toolkit for defining structured configuration languages. The principal workflow is an application supplying configuration text, parsing it as native HCL or HCL JSON, then decoding its attributes and blocks into application values; native expressions can also use application-provided variables and functions. The map includes declarative and struct decoders, dynamic-block and expression extensions, plus source-preserving writing and formatting. Edges follow README statements and shown imports or calls; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`hclsyntax/parser.go`](https://github.com/hashicorp/hcl/blob/main/hclsyntax/parser.go) (Native syntax), [`hclsimple/hclsimple.go`](https://github.com/hashicorp/hcl/blob/main/hclsimple/hclsimple.go) (One-step decode), [`cmd/hcldec/main.go`](https://github.com/hashicorp/hcl/blob/main/cmd/hcldec/main.go) (hcldec CLI), [`hclparse/parser.go`](https://github.com/hashicorp/hcl/blob/main/hclparse/parser.go) (Parser facade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_parsing["Parsing"]
  node_hclparse["Parser facade<br/>[parser.go]"]
  node_native["Native syntax<br/>[parser.go]"]
  node_jsonparse["HCL JSON<br/>[structure.go]"]
end

subgraph group_language["Language model"]
  node_model["Body and schema<br/>[schema.go]"]
  node_expressions["Expressions<br/>[expression.go]"]
  node_evaluation["Expression evaluation<br/>[eval_context.go]"]
end

subgraph group_decoding["Decoding"]
  node_simple["One-step decode<br/>[hclsimple.go]"]
  node_structdecode["Go struct decoder<br/>[decode.go]"]
  node_specdecode["Spec decoder<br/>[spec.go]"]
end

subgraph group_extensions["Extensions"]
  node_dynamicblocks["Dynamic blocks<br/>[expand_body.go]"]
  node_customdecode["Custom expressions<br/>[customdecode.go]"]
  node_typeexpr["Type expressions<br/>[get_type.go]"]
  node_userfunc["User functions<br/>[public.go]"]
  node_tryfunc["Try functions<br/>[tryfunc.go]"]
end

subgraph group_authoring["Authoring tools"]
  node_writer["Source-preserving writer<br/>[parser.go]"]
  node_formatter["Formatting<br/>[format.go]"]
  node_hcldeccli["hcldec CLI<br/>[main.go]"]
  node_speccli["CLI spec parser<br/>[spec.go]"]
end

node_application(("Calling application"))

node_application -->|"submits config"| node_hclparse
node_hclparse -->|"parses HCL"| node_native
node_hclparse -->|"parses JSON"| node_jsonparse
node_native -->|"produces structure"| node_model
node_jsonparse -->|"produces structure"| node_model
node_native -->|"parses expressions"| node_expressions
node_application -->|"loads config"| node_simple
node_simple -->|"parses HCL"| node_native
node_simple -->|"parses JSON"| node_jsonparse
node_simple -->|"decodes body"| node_structdecode
node_application -->|"decodes to structs"| node_structdecode
node_application -->|"decodes by spec"| node_specdecode
node_specdecode -->|"consumes body"| node_model
node_application -->|"provides variables"| node_evaluation
node_expressions -->|"evaluates values"| node_evaluation
node_application -->|"uses extension"| node_dynamicblocks
node_tryfunc -->|"evaluates closures"| node_customdecode
node_application -.->|"uses extension"| node_typeexpr
node_application -.->|"uses extension"| node_userfunc
node_application -.->|"edits configuration"| node_writer
node_writer -->|"parses tokens"| node_native
node_application -->|"formats source"| node_formatter
node_formatter -->|"formats tokens"| node_writer
node_application -.->|"runs decoder CLI"| node_hcldeccli
node_hcldeccli -->|"decodes by spec"| node_specdecode
node_hcldeccli -->|"parses inputs"| node_hclparse
node_hcldeccli -.->|"loads spec"| node_speccli

click node_hclparse "https://github.com/hashicorp/hcl/blob/main/hclparse/parser.go"
click node_native "https://github.com/hashicorp/hcl/blob/main/hclsyntax/parser.go"
click node_jsonparse "https://github.com/hashicorp/hcl/blob/main/json/structure.go"
click node_model "https://github.com/hashicorp/hcl/blob/main/schema.go"
click node_expressions "https://github.com/hashicorp/hcl/blob/main/hclsyntax/expression.go"
click node_evaluation "https://github.com/hashicorp/hcl/blob/main/eval_context.go"
click node_simple "https://github.com/hashicorp/hcl/blob/main/hclsimple/hclsimple.go"
click node_structdecode "https://github.com/hashicorp/hcl/blob/main/gohcl/decode.go"
click node_specdecode "https://github.com/hashicorp/hcl/blob/main/hcldec/spec.go"
click node_dynamicblocks "https://github.com/hashicorp/hcl/blob/main/ext/dynblock/expand_body.go"
click node_customdecode "https://github.com/hashicorp/hcl/blob/main/ext/customdecode/customdecode.go"
click node_typeexpr "https://github.com/hashicorp/hcl/blob/main/ext/typeexpr/get_type.go"
click node_userfunc "https://github.com/hashicorp/hcl/blob/main/ext/userfunc/public.go"
click node_tryfunc "https://github.com/hashicorp/hcl/blob/main/ext/tryfunc/tryfunc.go"
click node_writer "https://github.com/hashicorp/hcl/blob/main/hclwrite/parser.go"
click node_formatter "https://github.com/hashicorp/hcl/blob/main/hclwrite/format.go"
click node_hcldeccli "https://github.com/hashicorp/hcl/blob/main/cmd/hcldec/main.go"
click node_speccli "https://github.com/hashicorp/hcl/blob/main/cmd/hcldec/spec.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hclparse,node_native,node_jsonparse toneBlue
class node_model,node_expressions,node_evaluation toneAmber
class node_simple,node_structdecode,node_specdecode toneMint
class node_dynamicblocks,node_customdecode,node_typeexpr,node_userfunc,node_tryfunc toneRose
class node_writer,node_formatter,node_hcldeccli,node_speccli,node_application toneIndigo
```

## Components

### Parsing

- [Parser facade](https://github.com/hashicorp/hcl/blob/main/hclparse/parser.go): `hclparse/parser.go`
- [Native syntax](https://github.com/hashicorp/hcl/blob/main/hclsyntax/parser.go): `hclsyntax/parser.go`
- [HCL JSON](https://github.com/hashicorp/hcl/blob/main/json/structure.go): `json/structure.go`

### Language model

- [Body and schema](https://github.com/hashicorp/hcl/blob/main/schema.go): `schema.go`
- [Expressions](https://github.com/hashicorp/hcl/blob/main/hclsyntax/expression.go): `hclsyntax/expression.go`
- [Expression evaluation](https://github.com/hashicorp/hcl/blob/main/eval_context.go): `eval_context.go`

### Decoding

- [One-step decode](https://github.com/hashicorp/hcl/blob/main/hclsimple/hclsimple.go): `hclsimple/hclsimple.go`
- [Go struct decoder](https://github.com/hashicorp/hcl/blob/main/gohcl/decode.go): `gohcl/decode.go`
- [Spec decoder](https://github.com/hashicorp/hcl/blob/main/hcldec/spec.go): `hcldec/spec.go`

### Extensions

- [Dynamic blocks](https://github.com/hashicorp/hcl/blob/main/ext/dynblock/expand_body.go): `ext/dynblock/expand_body.go`
- [Custom expressions](https://github.com/hashicorp/hcl/blob/main/ext/customdecode/customdecode.go): `ext/customdecode/customdecode.go`
- [Type expressions](https://github.com/hashicorp/hcl/blob/main/ext/typeexpr/get_type.go): `ext/typeexpr/get_type.go`
- [User functions](https://github.com/hashicorp/hcl/blob/main/ext/userfunc/public.go): `ext/userfunc/public.go`
- [Try functions](https://github.com/hashicorp/hcl/blob/main/ext/tryfunc/tryfunc.go): `ext/tryfunc/tryfunc.go`

### Authoring tools

- [Source-preserving writer](https://github.com/hashicorp/hcl/blob/main/hclwrite/parser.go): `hclwrite/parser.go`
- [Formatting](https://github.com/hashicorp/hcl/blob/main/hclwrite/format.go): `hclwrite/format.go`
- [hcldec CLI](https://github.com/hashicorp/hcl/blob/main/cmd/hcldec/main.go): `cmd/hcldec/main.go`
- [CLI spec parser](https://github.com/hashicorp/hcl/blob/main/cmd/hcldec/spec.go): `cmd/hcldec/spec.go`

### Other components

- **Calling application**

## Connections

- Calling application → Parser facade: submits config
- Parser facade → Native syntax: parses HCL (evidence: `hclparse/parser.go`)
- Parser facade → HCL JSON: parses JSON (evidence: `hclparse/parser.go`)
- Native syntax → Body and schema: produces structure
- HCL JSON → Body and schema: produces structure
- Native syntax → Expressions: parses expressions
- Calling application → One-step decode: loads config
- One-step decode → Native syntax: parses HCL (evidence: `hclsimple/hclsimple.go`)
- One-step decode → HCL JSON: parses JSON (evidence: `hclsimple/hclsimple.go`)
- One-step decode → Go struct decoder: decodes body (evidence: `hclsimple/hclsimple.go`)
- Calling application → Go struct decoder: decodes to structs
- Calling application → Spec decoder: decodes by spec
- Spec decoder → Body and schema: consumes body (evidence: `hcldec/spec.go`)
- Calling application → Expression evaluation: provides variables
- Expressions → Expression evaluation: evaluates values
- Calling application → Dynamic blocks: uses extension
- Try functions → Custom expressions: evaluates closures (evidence: `ext/tryfunc/tryfunc.go`)
- Calling application → Type expressions: uses extension
- Calling application → User functions: uses extension
- Calling application → Source-preserving writer: edits configuration
- Source-preserving writer → Native syntax: parses tokens (evidence: `hclwrite/parser.go`)
- Calling application → Formatting: formats source
- Formatting → Source-preserving writer: formats tokens (evidence: `hclwrite/format.go`)
- Calling application → hcldec CLI: runs decoder CLI
- hcldec CLI → Spec decoder: decodes by spec (evidence: `cmd/hcldec/main.go`)
- hcldec CLI → Parser facade: parses inputs (evidence: `cmd/hcldec/main.go`)
- hcldec CLI → CLI spec parser: loads spec
