﻿---
title: First Principles
description: The navigation system is built on two types of principles: These define what the navigation system does and why: Two-Phase Loading - Separate configuration...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/first-principles
---

# First Principles
The navigation system is built on two types of principles:

## [Functional Principles](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/functional-principles)

These define **what** the navigation system does and **why**:
1. **Two-Phase Loading** - Separate configuration resolution from navigation construction
2. **Single Documentation Source** - All paths relative to docset root
3. **URL Building is Dynamic** - URLs calculated on-demand, not stored
4. **Navigation Roots Can Be Re-homed** - O(1) URL prefix changes
5. **Navigation Scope via HomeProvider** - Scoped URL calculation contexts
6. **Index Files Determine URLs** - Folders and indexes share URLs
7. **File Structure Mirrors Navigation** - Predictable, maintainable structure
8. **Acyclic Graph Structure** - Tree with no cycles, unique URLs
9. **Phantom Nodes** - Acknowledge content without including it

[Read Functional Principles →](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/functional-principles)

## [Technical Principles](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/technical-principles)

These define **how** the navigation system is implemented:
1. **Generic Type System** - Covariance enables static typing without runtime casts
2. **Provider Pattern** - Decouples URL calculation from tree structure
3. **Lazy URL Calculation** - Smart caching with automatic invalidation

[Read Technical Principles →](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/technical-principles)
---


## Quick Reference

**For understanding architecture:** Start with [Functional Principles](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/functional-principles)
**For implementation details:** See [Technical Principles](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/technical-principles)
**For visual examples:** See [Visual Walkthrough](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/visual-walkthrough)
**For specific topics:**
- How assembly works: [Assembler Process](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/assembler-process)
- How re-homing works: [Home Provider Architecture](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/home-provider-architecture)
- Two-phase approach: [Two-Phase Loading](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/two-phase-loading)
- Node reference: [Node Types](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2679/development/navigation/node-types)