﻿---
title: Core architecture concepts and building blocks
description: This section explains the core concepts and building blocks that make up the docs-builder architecture. Understanding these concepts will help you work...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks
---

# Core architecture concepts and building blocks
This section explains the core concepts and building blocks that make up the docs-builder architecture. Understanding these concepts will help you work effectively with distributed documentation and cross-repository linking.

## Core concepts


### [Documentation Set](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/documentation-set)

The fundamental unit of documentation - a single folder containing the documentation for one repository. Each documentation set can be built, versioned, and maintained independently.

### [Assembled Documentation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/assembled-documentation)

The product of combining multiple documentation sets into a unified documentation website with global navigation. This enables a seamless user experience across multiple repositories.

### [Distributed Documentation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/distributed-documentation)

The architectural approach that allows documentation sets to be built independently while maintaining link integrity across repositories. This enables teams to work autonomously without blocking each other.

## Link management infrastructure


### [Link Service](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/link-service)

The central S3-backed service where Link Index files are published and stored. This enables distributed validation and build resilience.

### [Link Index](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/link-index)

A JSON file (`links.json`) containing all linkable resources for a specific repository branch. Published to the Link Service after each successful build.

### [Link Catalog](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/link-catalog)

A catalog file listing all available Link Index files across all repositories and branches. Used by the assembler to coordinate builds and by documentation builds for validation.

## Cross-repository linking


### [Outbound Cross-links](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/outbound-cross-links)

Links from your documentation to other documentation sets. Validated against published Link Index files to ensure they're correct.

### [Inbound Cross-links](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/inbound-cross-links)

Links from other documentation sets to yours. Validated to prevent breaking changes when you move or delete content.

## Navigation


### [Documentation Set Navigation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/documentation-set-navigation)

How individual documentation sets organize their content through TOC sections in `docset.yml` and `toc.yml` files. Each repository controls its own internal navigation structure, including file and folder organization.

### [Global Navigation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2454/building-blocks/global-navigation)

How multiple documentation sets are organized together in assembled documentation through `navigation.yml`. Uses cross-link syntax to reference TOC sections from different repositories and enables cross-repository content organization.

## How it all works together

1. Each repository builds its documentation set independently
2. Successful builds publish a Link Index to the Link Service
3. The Link Catalog catalogs all available Link Index files
4. Documentation builds validate cross-links using these Link Index files
5. The assembler combines documentation sets using the Link Catalog
6. Teams can work independently while maintaining link integrity across repositories