Architecture - Bengal

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

Rendering Pipeline

How Bengal transforms Markdown to HTML

Subsystems

Specialized feature subsystems

Tooling & CLI

Developer tools, CLI, server, and configuration

Meta & Operations

Performance, testing, and project structure

High-Level Architecture

graph TB subgraph "Entry Points" CLI[CLI bengal/cli/] Server[Dev Server bengal/server/] end subgraph "Core Build Pipeline" Discovery[Discovery bengal/content/discovery/] Orchestration[Orchestration bengal/orchestration/] Rendering[Rendering bengal/rendering/] PostProcess[Post-Processing bengal/postprocess/] end subgraph "Object Model" Site[Site bengal/core/site/] Pages[Pages bengal/core/page/] Sections[Sections bengal/core/section/] Assets[Assets bengal/core/asset/] Menus[Menus bengal/core/menu.py] NavTree[NavTree bengal/core/nav_tree.py] end subgraph "Contracts" Protocols[Protocols bengal/protocols/] end subgraph "Supporting Systems" Cache[Build Cache bengal/cache/] Health[Health Checks bengal/health/] Autodoc[Autodoc bengal/autodoc/] Config[Config bengal/config/] Analysis[Analysis bengal/analysis/] Fonts[Fonts bengal/fonts/] Collections[Collections bengal/collections/] ContentLayer[Content Layer bengal/content/sources/] Output[CLI Output bengal/output/] Debug[Debug Tools 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
Build coordination	Orchestration
Markdown → HTML	Rendering Pipeline
Interface contracts	Protocol Layer
Design guidelines	Design Principles

In This Section

Core Architecture Data models and build coordination 7 pages

Rendering Pipeline How Bengal transforms Markdown to HTML 6 pages

Subsystems Specialized feature subsystems 9 pages

Tooling & CLI Developer tools, CLI, server, and configuration 5 pages

Meta & Operations Performance, testing, and project structure 5 pages

Design Principles Core patterns and philosophies guiding Bengal's architecture.