# sayi/poi-tl architecture

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

- Interactive diagram: https://gitdiagram.com/sayi/poi-tl
- Repository: https://github.com/sayi/poi-tl

## Overview

##### Main Components
- Core Template Engine (poi-tl): This module (under the “poi-tl” directory) orchestrates the template parsing, tag evaluation, and document generation. It contains packages for configuration, expressions, template parsing/resolving, rendering policies, and utilities.
- Plugin Modules: There are separate modules such as:
– poi-tl-plugin-highlight for code highlighting.
– poi-tl-plugin-markdown for transforming Markdown content into Word.
These plugins extend the base functionality through custom render policies and converters.
- CLI Module (poi-tl-cli): Provides a command‐line interface to drive the template engine.
- JSON Model Support (poi-tl-jsonmodel-support): Supplies additional support for mapping JSON data to rendering models.
- Schema Extension (poi-ooxml-schemas-extra): Contains additional or modified Apache POI XML schemas to support more features or custom elements in Word processing.

##### Layered and Modular Architecture
- At the lowest layer, include third-party libraries and dependencies:
– Apache POI (versions 3.16+ up to 5.1.0 and later) for low-level Word document operations.
– Other build and configuration files (pom.xml, .travis.yml, etc.) that facilitate integration and deployment.
- The Core Engine layer uses these libraries and handles parsing, template merging, tag replacement, and style management.
- The Plugin layer sits on top of the core engine and provides additional functionality. This layer should detail how the core engine “plugs in” custom functions (like those managing Markdown or syntax highlighting).
- The Utility layer comprises supporting packages (e.g., converters, resolvers, renderers, and common utilities) that enrich the processing workflow.
- The Client Access layer includes the CLI and any external APIs or integration points (like JSON input handling) that allow users or downstream systems to interact with the engine.

- That the Core Engine makes calls to Apache POI and the extended schema module (poi-ooxml-schemas-extra) to manipulate and generate Word documents.
- Dependency flows: for example, the JSON Model Support module feeds data models into the template resolution process.

##### Architectural Patterns and Design Principles
- Use a layered architecture (presentation/command layer; core business/template engine; plugin/extension modules; and integration with external libraries).
- Modularity and extensibility: the plugins and custom functions illustrate the pluggable architecture.
- “logic-less” design pattern, where only tag placeholders are used in templates, keeping business logic separated from the presentation.
- Use of builder patterns in configuration (e.g., ConfigureBuilder in the core module) and abstract render policies that allow for different rendering behaviors.

##### Instructing the Principal Software Engineer
– “XWPFTemplate (Core Engine): Handles template compilation, rendering and document generation.”
– “Highlight Plugin: Converts code blocks via custom render policies.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Access Layer"
      CLI["CLI Module (Command Line Interface)"]:::client
      JSON["JSON Model Support (Data Mapping)"]:::client
    end

    subgraph "Core Engine Layer"
      CT["Core Template Engine (poi-tl): Parses templates, replaces tags, and generates Word documents"]:::core
    end

    subgraph "Plugin Layer"
      HPLUGIN["Highlight Plugin: Applies code highlighting with custom render policies"]:::plugin
      MPLUGIN["Markdown Plugin: Converts Markdown content for Word"]:::plugin
    end

    subgraph "External Dependencies"
      POI["Apache POI: Handles low-level Word document operations"]:::external
      SCHEMA["Schema Extension: Custom Apache POI XML Schemas (poi-ooxml-schemas-extra)"]:::external
    end

    CLI -->|"invokes"| CT
    JSON -->|"suppliesData"| CT

    CT -->|"callsHighlight"| HPLUGIN
    CT -->|"callsMarkdown"| MPLUGIN
    CT -->|"usesPOI"| POI
    CT -->|"extendsSchema"| SCHEMA

    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef plugin fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef client fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef external fill:#F4A460,stroke:#000,stroke-width:2px;

    click CT "https://github.com/sayi/poi-tl/tree/master/poi-tl"
    click HPLUGIN "https://github.com/sayi/poi-tl/tree/master/poi-tl-plugin-highlight"
    click MPLUGIN "https://github.com/sayi/poi-tl/tree/master/poi-tl-plugin-markdown"
    click CLI "https://github.com/sayi/poi-tl/tree/master/poi-tl-cli"
    click JSON "https://github.com/sayi/poi-tl/tree/master/poi-tl-jsonmodel-support"
    click SCHEMA "https://github.com/sayi/poi-tl/tree/master/poi-ooxml-schemas-extra"
```
