# shopify/liquid architecture

> Architecture diagram of the GitHub repository shopify/liquid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shopify/liquid
- Repository: https://github.com/shopify/liquid

## Overview

##### Project type and purpose
- This is an open-source Ruby library implementing the Liquid template engine (liquid.gemspec, lib/liquid).
- Its purpose is to parse, compile, and render user-supplied templates in a safe, stateless, extensible way.

##### File structure
- Top-level:
- Configuration & CI (.github/, .rubocop*, Gemfile, Rakefile, LICENSE, README.md)
- Source code (lib/liquid/)
- Example server (example/)
- Performance harness (performance/)
- Automated tests (test/)
- Key architectural clues:
- lib/liquid/lexer.rb, tokenizer.rb → lexical analysis
- parser.rb, parser_switching.rb → syntax analysis
- document.rb, parse_tree_visitor.rb → AST representation & traversal
- context.rb, environment.rb, registers.rb → runtime execution context & configuration
- tags/, standardfilters.rb → extension points for tags & filters
- partial_cache.rb, profiler/ → caching & performance hooks
- template_factory.rb & template.rb → user API for parse/compile/render separation

##### Insights from README
- Emphasizes two-step model: parse/compile vs. render
- Introduces “Environment” as a scoped registry of tags/filters
- Mentions error modes, strict rendering, usage tracking
- Encourages modularity & safe execution of untrusted templates

a. Main components:
1. Client API (Liquid::Template)
2. Lexer/Tokenizer
3. Parser & Parser Switching
4. AST (Document, BlockBody, Tag, Variable, Expression nodes)
5. Template Factory & Compiled Template
6. Environment (registry of tags, filters, file system resolver, error mode)
7. Render Context (variables hash, registers, resource limits)
8. Filter & Tag implementations (standardfilters.rb, lib/liquid/tags/)
9. Partial Cache & Profiler Hooks
10. Output Stream

b. Relationships and interactions:
- The client calls Template.parse(source, environment)
→ Source fed into Lexer → Tokens fed into Parser
→ Parser produces AST (Document) → Compiled Template object stored/cached
- The client calls Template.render(vars, options)
→ Render Context built from Environment + vars + options
→ AST traversed by parse_tree_visitor, evaluating nodes in Context
→ Tags and Variables dispatched to registered implementations
→ Partial_cache used for includes; profiler hooks track execution
→ Output concatenated into final string

c. Architectural patterns & principles:
- Pipeline: lex → parse → compile → render
- Stateless compilation: parse once, render many
- Dependency injection: Environment encapsulates tags/filters
- Visitor pattern: parse_tree_visitor walks AST
- Strategy/Registry: filters and tags registered per environment
- Caching: partial_cache for fragments, TemplateFactory caching

d. Key technologies/frameworks:
- Ruby (MRI, .ruby-version)
- Rake for tasks (Rakefile)
- RuboCop for linting
- GitHub Actions for CI (.github/workflows)

##### Be detailed and exhaustive
- Major lib/liquid subdirectories and show how they plug into the core pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Compiler Phases"
    direction TB
    LibEntry["Library Entry Point\nlib/liquid.rb"]:::compile
    Lexer["Lexer\nlexer.rb"]:::compile
    Tokenizer["Tokenizer\ntokenizer.rb"]:::compile
    ParserSwitch["Parser & Switching\nparser.rb\nparser_switching.rb"]:::compile
    ParseContext["Parse Context\nparse_context.rb"]:::compile
    AST["AST Nodes\ndocument.rb\nblock_body.rb\ntag.rb\nvariable.rb\nexpression.rb"]:::compile
    TemplateFactory["Template Factory\ntemplate_factory.rb"]:::compile
  end

  subgraph "Runtime & Environment"
    direction TB
    Environment["Environment\nenvironment.rb\nfile_system.rb\nerrors.rb"]:::runtime
    Context["Render Context\ncontext.rb\nregisters.rb\nresource_limits.rb"]:::runtime
    PartialCache["Partial Cache\npartial_cache.rb"]:::runtime
    Profiler["Profiler\nprofiler.rb\nprofiler/hooks.rb"]:::runtime
  end

  subgraph "Extension Points"
    direction TB
    Filters["Standard Filters\nstandardfilters.rb"]:::extension
    TagsImpl["Tag Implementations\ntags/"]:::extension
    CoreTags["Core Tag Extensions\ntag/"]:::extension
  end

  subgraph "Client Interaction"
    direction TB
    Client["Client API\ntemplate.rb"]:::compile
  end

  Client -->|parse| LibEntry
  LibEntry --> Lexer
  Lexer --> Tokenizer
  Tokenizer --> ParserSwitch
  ParserSwitch --> ParseContext
  ParseContext --> AST
  AST --> TemplateFactory
  TemplateFactory -->|Compiled Template| Environment
  Client -->|render| Context
  Environment --> Context
  Context --> AST
  AST -->|visit| Profiler
  AST -->|visit| PartialCache
  Context -->|lookup| Filters
  Context -->|lookup| TagsImpl
  Context -->|lookup| CoreTags
  Profiler --> Context
  PartialCache --> Context

  click Client "https://github.com/shopify/liquid/blob/main/lib/liquid/template.rb"
  click LibEntry "https://github.com/shopify/liquid/blob/main/lib/liquid.rb"
  click Lexer "https://github.com/shopify/liquid/blob/main/lib/liquid/lexer.rb"
  click Tokenizer "https://github.com/shopify/liquid/blob/main/lib/liquid/tokenizer.rb"
  click ParserSwitch "https://github.com/shopify/liquid/blob/main/lib/liquid/parser.rb"
  click ParserSwitch "https://github.com/shopify/liquid/blob/main/lib/liquid/parser_switching.rb"
  click ParseContext "https://github.com/shopify/liquid/blob/main/lib/liquid/parse_context.rb"
  click AST "https://github.com/shopify/liquid/blob/main/lib/liquid/document.rb"
  click AST "https://github.com/shopify/liquid/blob/main/lib/liquid/block_body.rb"
  click AST "https://github.com/shopify/liquid/blob/main/lib/liquid/tag.rb"
  click AST "https://github.com/shopify/liquid/blob/main/lib/liquid/variable.rb"
  click AST "https://github.com/shopify/liquid/blob/main/lib/liquid/expression.rb"
  click TemplateFactory "https://github.com/shopify/liquid/blob/main/lib/liquid/template_factory.rb"
  click Environment "https://github.com/shopify/liquid/blob/main/lib/liquid/environment.rb"
  click Environment "https://github.com/shopify/liquid/blob/main/lib/liquid/file_system.rb"
  click Environment "https://github.com/shopify/liquid/blob/main/lib/liquid/errors.rb"
  click Context "https://github.com/shopify/liquid/blob/main/lib/liquid/context.rb"
  click Context "https://github.com/shopify/liquid/blob/main/lib/liquid/registers.rb"
  click Context "https://github.com/shopify/liquid/blob/main/lib/liquid/resource_limits.rb"
  click Filters "https://github.com/shopify/liquid/blob/main/lib/liquid/standardfilters.rb"
  click TagsImpl "https://github.com/shopify/liquid/tree/main/lib/liquid/tags/"
  click CoreTags "https://github.com/shopify/liquid/tree/main/lib/liquid/tag/"
  click PartialCache "https://github.com/shopify/liquid/blob/main/lib/liquid/partial_cache.rb"
  click Profiler "https://github.com/shopify/liquid/blob/main/lib/liquid/profiler.rb"
  click Profiler "https://github.com/shopify/liquid/blob/main/lib/liquid/profiler/hooks.rb"

  classDef compile fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef runtime fill:#90EE90,stroke:#333,stroke-width:1px
  classDef extension fill:#FFA500,stroke:#333,stroke-width:1px
```
