# bkuhlmann/superfluid architecture

> Architecture diagram of the GitHub repository bkuhlmann/superfluid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bkuhlmann/superfluid
- Repository: https://github.com/bkuhlmann/superfluid

## Overview

Superfluid is a Ruby extension to Liquid that composes configurable environments, reusable filters and tags, and template rendering. The main workflow is a caller creating a renderer, rendering template text with data, and receiving rendered text; templates can also define and render in-memory partials. The README documents local and blank Liquid file systems as alternatives. Renderer, configuration, tag registry, and tag-container source was not sampled, so their internal wiring is shown only where documented, without asserting unverified calls.

Main entry points: [`lib/superfluid/renderer.rb`](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/renderer.rb) (Renderer), [`lib/superfluid/configuration.rb`](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/configuration.rb) (Configuration), [`lib/superfluid/environment.rb`](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/environment.rb) (Environment), [`lib/superfluid/registries/filter.rb`](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/registries/filter.rb) (Filter registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_superfluid["Superfluid API<br/>[superfluid.rb]"]
  node_renderer["Renderer<br/>[renderer.rb]"]
end

subgraph group_environment["Environment setup"]
  node_environment["Environment<br/>[environment.rb]"]
  node_configuration["Configuration<br/>[configuration.rb]"]
end

subgraph group_filters["Filter composition"]
  node_filter_registry["Filter registry<br/>[filter.rb]"]
  node_filter_container["Built-in filters<br/>[container.rb]"]
end

subgraph group_templates["Template rendering"]
  node_tag_registry["Tag registry<br/>[tag.rb]"]
  node_tag_container["Built-in tags<br/>[container.rb]"]
  node_template_tag["Template tag<br/>[template.rb]"]
  node_memory_fs[("Memory filesystem<br/>[memory.rb]")]
end

node_caller(("Application caller"))
node_liquid["Liquid engine"]
node_filter_commands["Custom filters"]
node_template_input["Template and data"]
node_rendered_output["Rendered text"]
node_other_filesystems["Liquid filesystems"]

node_caller -->|"creates renderer"| node_superfluid
node_superfluid -->|"builds environment"| node_environment
node_superfluid -->|"creates renderer"| node_renderer
node_renderer -->|"uses environment"| node_environment
node_environment -->|"uses configuration"| node_configuration
node_configuration -->|"configures filters"| node_filter_registry
node_configuration -->|"configures tags"| node_tag_registry
node_filter_registry -->|"loads defaults"| node_filter_container
node_environment -->|"registers filters"| node_filter_registry
node_environment -->|"registers tags"| node_tag_registry
node_filter_registry -->|"registers callables"| node_filter_commands
node_renderer -->|"renders through"| node_liquid
node_renderer -->|"accepts template and data"| node_template_input
node_liquid -->|"dispatches filters"| node_filter_registry
node_liquid -->|"resolves tags"| node_tag_registry
node_tag_registry -->|"provides tags"| node_tag_container
node_liquid -->|"executes tag"| node_template_tag
node_template_tag -->|"registers template"| node_memory_fs
node_liquid -->|"reads templates"| node_memory_fs
node_configuration -->|"defaults filesystem"| node_memory_fs
node_configuration -.->|"accepts alternative"| node_other_filesystems
node_liquid -->|"produces output"| node_rendered_output
node_renderer -->|"returns output"| node_rendered_output

click node_superfluid "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid.rb"
click node_renderer "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/renderer.rb"
click node_environment "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/environment.rb"
click node_configuration "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/configuration.rb"
click node_filter_registry "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/registries/filter.rb"
click node_filter_container "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/filters/container.rb"
click node_tag_registry "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/registries/tag.rb"
click node_tag_container "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/tags/container.rb"
click node_template_tag "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/tags/template.rb"
click node_memory_fs "https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/systems/memory.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_superfluid,node_renderer toneBlue
class node_environment,node_configuration toneAmber
class node_filter_registry,node_filter_container toneMint
class node_tag_registry,node_tag_container,node_template_tag,node_memory_fs toneRose
class node_caller,node_liquid,node_filter_commands,node_template_input,node_rendered_output,node_other_filesystems toneIndigo
```

## Components

### Public API

- [Superfluid API](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid.rb): `lib/superfluid.rb`
- [Renderer](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/renderer.rb): `lib/superfluid/renderer.rb`

### Environment setup

- [Environment](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/environment.rb): `lib/superfluid/environment.rb`
- [Configuration](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/configuration.rb): `lib/superfluid/configuration.rb`

### Filter composition

- [Filter registry](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/registries/filter.rb): `lib/superfluid/registries/filter.rb`
- [Built-in filters](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/filters/container.rb): `lib/superfluid/filters/container.rb`

### Template rendering

- [Tag registry](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/registries/tag.rb): `lib/superfluid/registries/tag.rb`
- [Built-in tags](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/tags/container.rb): `lib/superfluid/tags/container.rb`
- [Template tag](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/tags/template.rb): `lib/superfluid/tags/template.rb`
- [Memory filesystem](https://github.com/bkuhlmann/superfluid/blob/main/lib/superfluid/systems/memory.rb): `lib/superfluid/systems/memory.rb`

### Other components

- **Application caller**
- **Liquid engine**
- **Custom filters**
- **Template and data**
- **Rendered text**
- **Liquid filesystems**

## Connections

- Application caller → Superfluid API: creates renderer
- Superfluid API → Environment: builds environment
- Superfluid API → Renderer: creates renderer
- Renderer → Environment: uses environment
- Environment → Configuration: uses configuration
- Configuration → Filter registry: configures filters
- Configuration → Tag registry: configures tags
- Filter registry → Built-in filters: loads defaults
- Environment → Filter registry: registers filters
- Environment → Tag registry: registers tags
- Filter registry → Custom filters: registers callables
- Renderer → Liquid engine: renders through
- Renderer → Template and data: accepts template and data
- Liquid engine → Filter registry: dispatches filters
- Liquid engine → Tag registry: resolves tags
- Tag registry → Built-in tags: provides tags
- Liquid engine → Template tag: executes tag
- Template tag → Memory filesystem: registers template
- Liquid engine → Memory filesystem: reads templates
- Configuration → Memory filesystem: defaults filesystem
- Configuration → Liquid filesystems: accepts alternative
- Liquid engine → Rendered text: produces output
- Renderer → Rendered text: returns output