# Internal Architecture of the go-modern-guidelines Loading System: A Deep Dive

> Explore the internal architecture of the go-modern-guidelines loading system. Learn how it embeds, validates, and constructs runtime models for efficient guideline access.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: deep-dive
- Published: 2026-09-04

---

**The go-modern-guidelines loading system embeds guideline definitions directly into the binary using `//go:embed`, then validates the JSON through a strict schema parser before constructing a runtime model with O(1) ID lookups and version-filtered access.**

The JetBrains/go-modern-guidelines repository provides a lightweight tool for accessing modern Go coding recommendations. Its loading system is built around a self-contained pipeline that transforms embedded JSON data into a queryable runtime model without external file dependencies. Understanding this architecture reveals how the tool achieves zero runtime dependencies while maintaining strict data integrity and fast lookup performance.

## Core Components of the Loading Pipeline

The loading system consists of three primary components working in sequence to deliver guideline data from embedded binary assets to the public API.

### Embedded JSON Payload

The raw guideline definitions live in [`internal/guidelines/guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.json) and are compiled into the binary using the `//go:embed` directive. In [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go), the variable declaration embeds the JSON as a byte slice:

```go
//go:embed guidelines.json
var modernGoGuidelinesJSON []byte

```

This compile-time embedding ensures the application requires no external data files at runtime.

### Schema Parser and Validation

The [`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/schema/schema.go) file contains the validation logic that unmarshals and verifies the embedded JSON. The `schema.Parse` function returns a slice of `schema.Guideline` structs only after performing rigorous safety checks on the data structure.

### Runtime Model Builder

After validation, [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) converts the parsed `schema.Guideline` objects into the internal `modernGoGuideline` type. This component builds helper maps for fast lookups and supplies the public API methods including `ListText`, `ExplainText`, and `SupportedGuidelines`.

## Step-by-Step Loading Process

The pipeline executes a strict sequence from compile-time embedding to runtime API exposure.

### Compile-Time Embedding with go:embed

The process begins at compilation when the Go toolchain embeds [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) into the binary via the `//go:embed` directive. The `modernGoGuidelinesJSON` byte slice makes the entire dataset available as a static resource, eliminating file system dependencies and ensuring distribution as a single static binary.

### Strict Validation in schema.Parse

When the application initializes, the `mustLoadModernGoGuidelines` function invokes `schema.Parse(modernGoGuidelinesJSON)`. The parser performs several critical validations:

- **Identifier format validation** using `validID` to ensure guideline IDs follow naming conventions
- **Version format checking** with `goversion.IsMajorMinor` to confirm `since_version` fields match the "major.minor" pattern
- **Ordering verification** using `goversion.Compare` to guarantee the list is sorted newest-first
- **Content completeness checks** ensuring the `modernizer` flag, `category`, `impact`, `guideline`, `details`, and at least one example are present

If any validation fails, `schema.Parse` returns an error, causing `mustLoadModernGoGuidelines` to panic during initialization if the embedded data is malformed.

### Runtime Model Construction

For each validated `schema.Guideline`, the loader constructs a `modernGoGuideline` value by:

1. Concatenating the `Before` and `After` example slices into single strings using `strings.Join`
2. Copying remaining fields including `id`, `sinceVersion`, and `modernizer` flags
3. Storing the resulting slice in the package-level variable `modernGoGuidelines`

This transformation creates a flattened, runtime-optimized structure distinct from the raw schema representation.

### Lazy Lookup Helper Initialization

The system creates a lazily-initialized map named `guidelineByID` from the `modernGoGuidelines` slice. This map supports **O(1) lookups** for the `Explain` command, allowing immediate access to specific guidelines by their identifier without linear scanning.

### Version Filtering Logic

The `supportedGuidelines(targetGoVersion)` function iterates over `modernGoGuidelines` and filters entries based on their `sinceVersion`. Using `goversion.Compare`, it retains only guidelines applicable to the supplied target version (where guideline version ≤ target version). This enables the tool to show only relevant recommendations for specific Go releases.

## Public API and CLI Integration

The loading system exposes functionality through both programmatic interfaces and command-line tools.

### Programmatic API

The public API in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) provides three primary functions:

```go
// List all guidelines applicable to Go 1.20
txt, err := guidelines.ListText("1.20")
if err != nil {
    log.Fatal(err)
}
fmt.Println(txt)

```

```go
// Retrieve detailed markdown descriptions for specific guidelines
details, err := guidelines.ExplainText([]string{"use_context", "no_interface_nil"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(details)

```

```go
// Determine the highest Go version covered by the guideline set
fmt.Println("Latest known version:", guidelines.LatestKnownVersion())

```

### CLI Wrapper

The entry point in [`main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/main.go) forwards command-line arguments to `cli.Run` in [`internal/cli/cli.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/cli/cli.go). This thin wrapper translates CLI invocations into calls to the loading system:

```bash

# List supported guidelines for Go 1.19

$ go-modern-guidelines list 1.19

# Show detailed help for specific IDs

$ go-modern-guidelines explain use_context no_interface_nil

```

The CLI delegates to the same `ListText` and `ExplainText` functions used by the programmatic API, ensuring consistent behavior across interfaces.

## Summary

- The system uses **`//go:embed`** to compile [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) directly into the binary, eliminating external file dependencies.
- **Validation** occurs in `schema.Parse` within [`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/schema/schema.go), checking ID formats, version strings, ordering, and content completeness.
- The **runtime model** converts schema structs into `modernGoGuideline` objects with concatenated example strings stored in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go).
- **O(1) lookups** are enabled via a lazy-initialized `guidelineByID` map for the Explain functionality.
- **Version filtering** uses `goversion.Compare` to show only guidelines relevant to a target Go version.
- The public API exposes **`ListText`**, **`ExplainText`**, and **`LatestKnownVersion`** functions used by both programmatic consumers and the CLI wrapper.

## Frequently Asked Questions

### How does go-modern-guidelines load data without external files?

The tool uses the **`//go:embed`** directive in [`internal/guidelines/guidelines.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/guidelines.go) to embed [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) as a byte slice at compile time. This embeds the JSON data directly into the compiled binary, allowing the application to access guideline definitions without reading external files at runtime.

### What validation checks does the schema parser perform?

According to [`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/internal/guidelines/schema/schema.go), the parser validates identifier formats with `validID`, confirms `since_version` follows "major.minor" patterns using `goversion.IsMajorMinor`, verifies the list is ordered newest-first via `goversion.Compare`, and ensures required fields including `modernizer`, `category`, `impact`, and at least one example are present.

### How does the system handle different Go versions?

The `supportedGuidelines` function filters the full guideline list by comparing each entry's `sinceVersion` against the user-supplied target version using `goversion.Compare`. Only guidelines with a version less than or equal to the target are returned, allowing the tool to display contextually appropriate recommendations for specific Go releases.

### Where is the entry point for the loading system?

The entry point resides in [`main.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/main.go), which calls `cli.Run` to process command-line arguments. The CLI then invokes `mustLoadModernGoGuidelines`, which triggers the full loading pipeline: parsing the embedded JSON, validating through `schema.Parse`, building the runtime model, and initializing lookup maps before serving API requests.