# vapor/template-kit architecture

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

- Interactive diagram: https://gitdiagram.com/vapor/template-kit
- Repository: https://github.com/vapor/template-kit

## Overview

##### Project type and purpose
- Project type: Open-source Swift library (Vapor ecosystem).
- Purpose: Parse template files, build an AST, and render text output by merging templates with user‐provided data.

##### Main architectural components
A. Template Source Input
B. Parser & AST
C. Data Model & Encoder
D. Rendering Pipeline
E. Tag Extensions
F. Caching & Utilities
G. Integration Point (ViewRenderer / Vapor)

##### Component breakdown and interactions
1. Template Source Input
- Template files (e.g. “index.leaf”), raw text.
2. Parser & AST (Sources/TemplateKit/AST & Pipeline/TemplateParser)
- TemplateByteScanner: tokenizes input.
- TemplateParser: produces AST nodes (TemplateSyntax, TemplateTag, TemplateExpression, etc.).
- AST data structures (TemplateConditional, TemplateIterator, TemplateRaw, etc.)
3. Data Model & Encoder (Sources/TemplateKit/Data)
- TemplateData: unified data type.
- TemplateDataEncoder: encodes Swift types (structs, primitives) into TemplateData.
4. Rendering Pipeline (Sources/TemplateKit/Pipeline & ViewRenderer)
- TemplateRenderer: walks the AST, invokes TagRenderer for each tag node.
- PlaintextRenderer: handles nodes that are raw text or unparsed segments.
- TemplateSerializer: serializes AST for caching or reuse.
5. Tag Extensions (Sources/TemplateKit/Tag)
- TagRenderer & TagContext: generic plugin interfaces.
- Built-in tags: Var, If (conditional), Loop (iterator), DateFormat, Uppercase/Lowercase, Contains, Count, Print, Raw, Comment, Capitalize.
6. Caching & Utilities (Sources/TemplateKit/Pipeline/ASTCache & Utilities)
- ASTCache: caches parsed AST keyed by template path.
- Utilities: HTMLEscape, TemplateError, Exports.
7. Integration Point
- ViewRenderer & View: conform to Vapor’s View protocol.

##### Architectural patterns & design principles
- Separation of Concerns: parsing, data encoding, rendering, tagging, and caching are distinct modules.
- Plug-in architecture: tag implementations conform to a shared TagRenderer interface.
- Immutable AST: parsing and rendering phases are decoupled to allow caching and reuse.
- Swift Package Manager: Package.swift defines dependencies (no external services).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Template Source Input
    subgraph "A. Template Source Input"
        direction TB
        TemplateFile["Template File\n(index.leaf)"]:::source
    end
    click TemplateFile "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateSource.swift"

    %% Parser & AST
    subgraph "B. Parser & AST"
        direction TB
        Scanner["TemplateByteScanner"]:::core
        Parser["TemplateParser"]:::core
        subgraph "AST Data Structures"
            direction TB
            TCnd["TemplateConditional"]:::core
            TConst["TemplateConstant"]:::core
            TCustom["TemplateCustom"]:::core
            TDataCtx["TemplateDataContext"]:::core
            TEmbed["TemplateEmbed"]:::core
            TExpr["TemplateExpression"]:::core
            TIdent["TemplateIdentifier"]:::core
            TIter["TemplateIterator"]:::core
            TRaw["TemplateRaw"]:::core
            TSyn["TemplateSyntax"]:::core
            TSType["TemplateSyntaxType"]:::core
            TTag["TemplateTag"]:::core
        end
    end
    click Scanner "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Pipeline/TemplateByteScanner.swift"
    click Parser "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Pipeline/TemplateParser.swift"
    click TCnd "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateConditional.swift"
    click TConst "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateConstant.swift"
    click TCustom "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateCustom.swift"
    click TDataCtx "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateDataContext.swift"
    click TEmbed "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateEmbed.swift"
    click TExpr "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateExpression.swift"
    click TIdent "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateIdentifier.swift"
    click TIter "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateIterator.swift"
    click TRaw "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateRaw.swift"
    click TSyn "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateSyntax.swift"
    click TSType "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateSyntaxType.swift"
    click TTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/AST/TemplateTag.swift"

    %% Caching & Utilities
    subgraph "F. Caching & Utilities"
        direction TB
        ASTCache["ASTCache"]:::cache
        subgraph "Utilities"
            direction TB
            HTMLE["HTMLEscape"]:::cache
            TError["TemplateError"]:::cache
            Exports["Exports"]:::cache
        end
    end
    click ASTCache "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Pipeline/ASTCache.swift"
    click HTMLE "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Utilities/HTMLEscape.swift"
    click TError "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Utilities/TemplateError.swift"
    click Exports "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Utilities/Exports.swift"

    %% Data Model & Encoder
    subgraph "C. Data Model & Encoder"
        direction TB
        TData["TemplateData"]:::data
        TEncoder["TemplateDataEncoder"]:::data
        TDataRep["TemplateDataRepresentable"]:::data
        TStorage["TemplateDataStorage"]:::data
    end
    click TData "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Data/TemplateData.swift"
    click TEncoder "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Data/TemplateDataEncoder.swift"
    click TDataRep "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Data/TemplateDataRepresentable.swift"
    click TStorage "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Data/TemplateDataStorage.swift"

    %% Rendering Pipeline
    subgraph "D. Rendering Pipeline"
        direction TB
        Renderer["TemplateRenderer"]:::core
        Plaintext["PlaintextRenderer"]:::core
        Serializer["TemplateSerializer"]:::core
    end
    click Renderer "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Pipeline/TemplateRenderer.swift"
    click Plaintext "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Pipeline/PlaintextRenderer.swift"
    click Serializer "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Pipeline/TemplateSerializer.swift"

    %% Tag Extensions
    subgraph "E. Tag Extensions"
        direction TB
        subgraph "Interfaces"
            direction TB
            TagR["TagRenderer"]:::tag
            TagC["TagContext"]:::tag
        end
        subgraph "Built-in Tags"
            direction TB
            VarTag["Var"]:::tag
            IfTag["If"]:::tag
            LoopTag["Loop"]:::tag
            DateFmt["DateFormat"]:::tag
            UpTag["Uppercase"]:::tag
            LowTag["Lowercase"]:::tag
            ContainsTag["Contains"]:::tag
            CountTag["Count"]:::tag
            PrintTag["Print"]:::tag
            RawTag["Raw"]:::tag
            CommentTag["Comment"]:::tag
            CapTag["Capitalize"]:::tag
        end
    end
    click TagR "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/TagRenderer.swift"
    click TagC "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/TagContext.swift"
    click VarTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Var.swift"
    click ContainsTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Contains.swift"
    click CountTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Count.swift"
    click DateFmt "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/DateFormat.swift"
    click UpTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Uppercase.swift"
    click LowTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Lowercase.swift"
    click PrintTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Print.swift"
    click RawTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Raw.swift"
    click CommentTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Comment.swift"
    click CapTag "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/Tag/Capitalize.swift"

    %% Integration Point
    subgraph "G. Integration Point"
        direction TB
        ViewR["ViewRenderer"]:::integration
        View["View\n(Vapor)"]:::integration
    end
    click ViewR "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/ViewRenderer.swift"
    click View "https://github.com/vapor/template-kit/blob/master/Sources/TemplateKit/View.swift"

    %% Final Output
    Output["Rendered String Output"]:::core

    %% Connections
    TemplateFile -->|parse| Scanner
    Scanner --> Parser
    Parser --> TCnd
    Parser --> TConst
    Parser --> TCustom
    Parser --> TDataCtx
    Parser --> TEmbed
    Parser --> TExpr
    Parser --> TIdent
    Parser --> TIter
    Parser --> TRaw
    Parser --> TSyn
    Parser --> TSType
    Parser --> TTag
    Parser --> ASTCache
    ASTCache --> Parser
    ASTCache --> Renderer
    Renderer --> Plaintext
    Renderer --> Serializer
    Renderer --> Output
    Output --> ViewR
    ViewR --> View
    Renderer -->|uses| TData
    Renderer -->|uses| TEncoder
    Renderer -->|uses| TDataRep
    Renderer -->|uses| TStorage
    Renderer -->|invokes| TagR
    TagR --> VarTag
    TagR --> IfTag
    TagR --> LoopTag
    TagR --> DateFmt
    TagR --> UpTag
    TagR --> LowTag
    TagR --> ContainsTag
    TagR --> CountTag
    TagR --> PrintTag
    TagR --> RawTag
    TagR --> CommentTag
    TagR --> CapTag

    %% Styles
    classDef core fill:#cfe2f3,stroke:#0066cc,stroke-width:2px;
    classDef data fill:#d9ead3,stroke:#33a02c,stroke-width:2px;
    classDef tag fill:#fff2cc,stroke:#b58900,stroke-width:2px;
    classDef cache fill:#fce5cd,stroke:#d35400,stroke-width:2px;
    classDef integration fill:#e0bbe4,stroke:#6a1b9a,stroke-width:2px;
    classDef source fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px;
```
