# apache/velocity-engine architecture

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

- Interactive diagram: https://gitdiagram.com/apache/velocity-engine
- Repository: https://github.com/apache/velocity-engine

## Overview

##### Main Components

a. Core Engine Components:
- Template Parser
- Runtime Engine
- Context Management
- Resource Management
- Introspection System
- Event Handling System

b. Extension Points:
- Spring Support Module
- Scripting Engine (JSR-223)
- Resource Loaders
- Custom Parser Support

##### Architectural Layers

**┌─────────────────────────────────────────────────────────┐**
- Integration Layer                      │
- ┬─────────────────┬──────────────────┤
- Spring Support   │ JSR-223 Support │  Custom Parsers  │
- ┬───────┴────────┬────────┴────────┬─────────┘

**┌───────────┴────────────────┴──────────────────┴─────────┐**
- Core Engine                           │
- ┤
- ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
- Parser    │  │   Runtime    │  │    Context     │  │
- Subsystem  │◄─┤   Engine     │◄─┤   Management   │  │
- ┘  └──────────────┘  └────────────────┘  │
- ▲               ▲                   ▲           │

- ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
- Resource   │  │    Event     │  │  Introspection │  │
- Management │  │   Handling   │  │     System     │  │
- ┘  └──────────────┘  └────────────────┘  │
- ┘
- ▲                ▲                ▲
**┌───────────┴────────────────┴────────────────┴───────────┐**
- Resource Loaders                        │
- ┬──────────────┬────────────────┬──────────┤
- File     │  Classpath   │   Database     │  String  │
- Loader    │    Loader    │    Loader      │  Loader  │
- ┴──────────────┴────────────────┴──────────┘

##### Key Relationships
- Template parsing flow through the system
- Resource loading pathways
- Context propagation
- Event handling chain
- Extension point integration

##### Important Implementation Details
- VelocityEngine as the central component
- Parser customization capability
- Resource loader chain
- Event handling pipeline
- Demonstrate the context management flow

##### Additional Notes
- Version information
- Java 8+ requirement

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef integration fill:#e1f5fe,stroke:#01579b
    classDef core fill:#e8f5e9,stroke:#1b5e20
    classDef resource fill:#fff3e0,stroke:#e65100
    classDef default stroke-width:2px

    %% Integration Layer
    subgraph Integration
        Spring["Spring Support"]
        JSR["JSR-223 Support"]
        CustomP["Custom Parsers"]
    end

    %% Core Engine Layer
    subgraph CoreEngine
        VEngine["VelocityEngine"]:::core
        Parser["Parser Subsystem"]:::core
        Runtime["Runtime Engine"]:::core
        Context["Context Management"]:::core
        Resource["Resource Management"]:::core
        Event["Event Handling"]:::core
        Introspect["Introspection System"]:::core
    end

    %% Resource Loaders Layer
    subgraph ResourceLoaders
        FileLoader["File Loader"]:::resource
        ClassLoader["Classpath Loader"]:::resource
        DBLoader["Database Loader"]:::resource
        StrLoader["String Loader"]:::resource
    end

    %% Relationships
    Spring --> VEngine
    JSR --> VEngine
    CustomP --> Parser

    VEngine --> Parser
    VEngine --> Runtime
    VEngine --> Context
    VEngine --> Resource
    VEngine --> Event
    VEngine --> Introspect

    Resource --> FileLoader
    Resource --> ClassLoader
    Resource --> DBLoader
    Resource --> StrLoader

    %% Click Events
    click VEngine "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/app/VelocityEngine.java"
    click Parser "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/runtime/parser/Parser.java"
    click Context "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/context/Context.java"
    click Resource "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/runtime/resource/ResourceManager.java"
    click Introspect "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/util/introspection/Introspector.java"
    click Event "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/app/event/EventHandler.java"
    click Spring "https://github.com/apache/velocity-engine/blob/master/spring-velocity-support/src/main/java/org/apache/velocity/spring/VelocityEngineFactory.java"
    click JSR "https://github.com/apache/velocity-engine/blob/master/velocity-engine-scripting/src/main/java/org/apache/velocity/script/VelocityScriptEngine.java"
    click FileLoader "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/runtime/resource/loader/FileResourceLoader.java"
    click ClassLoader "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/runtime/resource/loader/ClasspathResourceLoader.java"
    click DBLoader "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/runtime/resource/loader/DataSourceResourceLoader.java"
    click StrLoader "https://github.com/apache/velocity-engine/blob/master/velocity-engine-core/src/main/java/org/apache/velocity/runtime/resource/loader/StringResourceLoader.java"
    click CustomP "https://github.com/apache/velocity-engine/blob/master/velocity-custom-parser-example/src/test/java/org/apache/velocity/runtime/parser/CustomParserTestCase.java"
```
