# Architecture

URL: /bengal/docs/reference/architecture/
Section: architecture
Description: High-level architecture overview of Bengal

---

> For a complete page index, fetch /bengal/llms.txt.

Bengal is organized as a set of small subsystems with clear boundaries. Use this section to orient yourself and then jump to the specific subsystem you are changing.

## How to use this section

- Start with the overview diagram on this page.

- Use the cards to jump to a subsystem.

- Prefer subsystem pages over repeating context here.

Core Architecture

Data models and build coordination

(/bengal/docs/reference/architecture/core/)

Rendering Pipeline

How Bengal transforms Markdown to HTML

(/bengal/docs/reference/architecture/rendering/)

Subsystems

Specialized feature subsystems

(/bengal/docs/reference/architecture/subsystems/)

Tooling & CLI

Developer tools, CLI, server, and configuration

(/bengal/docs/reference/architecture/tooling/)

Meta & Operations

Performance, testing, and project structure

(/bengal/docs/reference/architecture/meta/)

## High-Level Architecture

graph TB
subgraph "Entry Points"
CLI[CLI<br/>bengal/cli/]
Server[Dev Server<br/>bengal/server/]
end

subgraph "Core Build Pipeline"
Discovery[Discovery<br/>bengal/content/discovery/]
Orchestration[Orchestration<br/>bengal/orchestration/]
Rendering[Rendering<br/>bengal/rendering/]
PostProcess[Post-Processing<br/>bengal/postprocess/]
end

subgraph "Object Model"
Site[Site<br/>bengal/core/site/]
Pages[Pages<br/>bengal/core/page/]
Sections[Sections<br/>bengal/core/section/]
Assets[Assets<br/>bengal/core/asset/]
Menus[Menus<br/>bengal/core/menu.py]
NavTree[NavTree<br/>bengal/core/nav_tree.py]
end

subgraph "Contracts"
Protocols[Protocols<br/>bengal/protocols/]
end

subgraph "Supporting Systems"
Cache[Build Cache<br/>bengal/cache/]
Health[Health Checks<br/>bengal/health/]
Autodoc[Autodoc<br/>bengal/autodoc/]
Config[Config<br/>bengal/config/]
Analysis[Analysis<br/>bengal/analysis/]
Fonts[Fonts<br/>bengal/fonts/]
Collections[Collections<br/>bengal/collections/]
ContentLayer[Content Layer<br/>bengal/content/sources/]
Output[CLI Output<br/>bengal/output/]
Debug[Debug Tools<br/>bengal/debug/]
end

CLI --> Site
Server --> Site
Site --> Discovery
Discovery --> Pages
Discovery --> Sections
Discovery --> Assets
Site --> Orchestration
Orchestration --> Menus
Orchestration --> Rendering
Site --> NavTree
Sections -.->|"builds from"| NavTree
Menus -.->|"used by"| Rendering
NavTree -.->|"used by"| Rendering
Rendering --> PostProcess
Cache -.->|"cache checks"| Orchestration
Health -.->|"post-build validation"| Orchestration
Autodoc -.->|"generates"| Pages
Config -.->|"configuration"| Site
Analysis -.->|"analyzes"| Site
Fonts -.->|"font files"| Orchestration
Fonts -.->|"social cards"| PostProcess
Collections -.->|"schema validation"| Discovery
ContentLayer -.->|"remote sources"| Collections
Output -.->|"terminal output"| CLI
Debug -.->|"diagnostics"| Site
Protocols -.->|"contracts"| Rendering
Protocols -.->|"contracts"| Cache
Protocols -.->|"contracts"| Orchestration

## Key Flows

Flow
Path

Build
CLI → Site → Discovery → Orchestration → Rendering → Post-process

Dev server
Watch → Incremental rebuild → Serve output

Template context
Site + Page + NavTree → Rendering

## Quick Links

Topic
Page

Data models (Site, Page, Section)
Object Model (core/object-model/)

Build coordination
Orchestration (core/orchestration/)

Markdown → HTML
Rendering Pipeline (rendering/rendering/)

Interface contracts
Protocol Layer (meta/protocols/)

Design guidelines
Design Principles (design-principles/)

## In This Section

Core Architecture (/docs/reference/architecture/core/)

Data models and build coordination

7 pages

Rendering Pipeline (/docs/reference/architecture/rendering/)

How Bengal transforms Markdown to HTML

6 pages

Subsystems (/docs/reference/architecture/subsystems/)

Specialized feature subsystems

9 pages

Tooling & CLI (/docs/reference/architecture/tooling/)

Developer tools, CLI, server, and configuration

5 pages

Meta & Operations (/docs/reference/architecture/meta/)

Performance, testing, and project structure

5 pages

Design Principles (/bengal/docs/reference/architecture/design-principles/)

Core patterns and philosophies guiding Bengal's architecture.

Related Pages

Free-Threading (/bengal/docs/about/free-threading/)

How Bengal uses Python 3.14t for parallel page rendering

Related

Bengal 0.1.4 (/bengal/releases/0.1.4/)

Configuration system overhaul, asset pipeline improvements, HTML formatting, link checking, and major architecture enhancements

5 months ago

Bengal 0.1.9 (/bengal/releases/0.1.9/)

Architecture decomposition, Python 3.14 modernization, build performance, protocol migrations, and comprehensive docs audit

3 months ago

Bengal 0.3.0 (/bengal/releases/0.3.0/)

Immutable page pipeline, plugin system, structured concurrency, protocol-based architecture

1 month ago

architecture (/bengal/tags/architecture/)

overview (/bengal/tags/overview/)

design (/bengal/tags/design/)

systems (/bengal/tags/systems/)

components (/bengal/tags/components/)