# silentvoid13/templater architecture

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

- Interactive diagram: https://gitdiagram.com/silentvoid13/templater
- Repository: https://github.com/silentvoid13/templater

## Overview

##### Project type and purpose
- This is an Obsidian.md plugin (written in TypeScript) called “Templater,” aimed at providing a templating language and programmable functions inside Obsidian vaults. It hooks into the Obsidian app, registers commands and event listeners, parses and executes templates via internal and user-supplied functions, and renders results back into the editor or filesystem.

##### File structure
- Top-level build/deploy: esbuild.config.mjs, package.json, pnpm-lock.yaml, manifest.json, scripts/versions-updater.cjs.
- Documentation: docs/ (mdBook-powered docs).
- Source: src/ broken down into subfolders:
- core/ – Templater.ts (main engine), functions generator, parser
- editor/ – integration with the CodeMirror editor (Autocomplete, CursorJumper, custom modes)
- handlers/ – CommandHandler, EventHandler, FuzzySuggester
- settings/ – Settings definitions and render options, suggesters
- utils/ – logging, errors, constants, file handling helpers
- main.ts – plugin entry point
- Tests under tests/ mirror core modules.

##### Key insights from README
- The plugin defines a DSL for templates, can run arbitrary JS and system commands via internal modules (file, date, system, web, frontmatter, hooks, etc.).
- Core extensibility: internal-functions vs. user-functions.
- Lifecycle: initialize plugin → register commands/events → parse/execute templates on demand → output into notes or file system.

##### Main components
a. External Host:
- Obsidian Application & Plugin API
- OS / File System / Shell
- Network (for web functions)
b. Plugin Entry & Lifecycle:
- main.ts → Plugin Initialization
- Plugin API registrations (commands, events)
c. Handlers & UI Integration:
- CommandHandler → user-triggered commands
- EventHandler → on-file-change, on-editor-focus
- FuzzySuggester & custom overlays (Autocomplete)
d. Core Engine:
- Parser (builds AST from template text)
- FunctionsGenerator (prepares internal + user functions)
- InternalFunctions modules (system, file, date, web, frontmatter, hooks)
- UserFunctions modules
e. Editor Adapter:
- Editor.ts → applies replacements, moves cursor, inserts text
f. Settings & Configuration:
- Settings.ts & IntellisenseRenderOption → control behavior & UI
g. Utilities:
- Logging, Error handling, Constants, Utils
h. Build & Deployment:
- esbuild config → bundles TS → plugin.js
- manifest.json, styles.css → plugin distribution

##### Relationships and interactions
- Obsidian App → loads plugin (main.ts) → calls onload()
- main.ts registers commands/event listeners via the Plugin API
- User triggers a Templater command in the editor → CommandHandler receives event
- CommandHandler passes raw template string → Parser → AST
- AST + context passed to FunctionsGenerator
- FunctionsGenerator invokes appropriate modules:
- InternalFunctions ↔ OS/FileSystem/Web
- UserFunctions ↔ custom JS in vault
- Computed result passed to Editor.ts for insertion/formatting
- EventHandler listens for changes to re-apply templates if needed
- Settings module governs which features are enabled and how suggestions render
- Utils support cross-cutting concerns (logging, error reporting)

##### Architectural patterns & design principles
- Modular separation: core engine, editor adapter, handlers, settings, utils
- Plugin lifecycle per Obsidian’s Plugin API
- Dependency injection: FunctionsGenerator loads only the modules needed
- Extensibility: easy to add new internal modules or user-defined functions
- Single Responsibility: each folder encapsulates one concern

##### Final advice
- Essential architectural elements: lifecycle, pipeline, modules, external dependencies.
- Keep labels concise and consistent with code names (e.g., “Parser (Parser.ts)”, “FileModule (InternalModuleFile.ts)”).
- Flow from top (Obsidian host) down through plugin, out to external systems, back into the editor.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Environment"
        Obsd["Obsidian Application"]:::host
        OS["OS / File System / Shell"]:::host
        Net["Network"]:::host
    end

    subgraph "Plugin Entry & Lifecycle"
        Main["main.ts"]:::entry
    end

    subgraph "Handlers & UI Integration"
        Cmd["CommandHandler"]:::handlers
        Ev["EventHandler"]:::handlers
        Sug["FuzzySuggester"]:::handlers
        Aut["Autocomplete"]:::handlers
        Cur["CursorJumper"]:::handlers
        Mods["Custom Editor Modes"]:::handlers
    end

    subgraph "Core Engine"
        Parser["Parser"]:::core
        FuncGen["FunctionsGenerator"]:::core
    end

    subgraph "Internal Modules"
        IntReg["InternalFunctions Registry"]:::modules
        IMBase["InternalModule Base"]:::modules
        Conf["InternalModuleConfig"]:::modules
        Date["InternalModuleDate"]:::modules
        FileM["InternalModuleFile"]:::modules
        Front["InternalModuleFrontmatter"]:::modules
        Hooks["InternalModuleHooks"]:::modules
        Sys["InternalModuleSystem"]:::modules
        Web["InternalModuleWeb"]:::modules
    end

    subgraph "User Modules"
        UFMgt["UserFunctions Manager"]:::modules
        UScript["UserScriptFunctions"]:::modules
        USys["UserSystemFunctions"]:::modules
    end

    subgraph "Editor Adapter"
        Editor["Editor.ts"]:::adapter
    end

    subgraph "Settings & Utils"
        Setts["Settings.ts"]:::support
        Intell["IntellisenseRenderOption"]:::support
        FSug["FileSuggester"]:::support
        FoldSug["FolderSuggester"]:::support
        GenSug["Generic Suggester"]:::support
        Const["Constants"]:::support
        Err["Error.ts"]:::support
        Log["Log.ts"]:::support
        TJDoc["TJDocFile.ts"]:::support
        Utils["Utils.ts"]:::support
    end

    subgraph "Build & Deployment"
        Esb["esbuild.config.mjs"]:::build
        Manif["manifest.json"]:::build
        VerUp["versions-updater.cjs"]:::build
    end

    %% Connections
    Obsd -->|loads plugin| Main
    OS -->|FS/Shell calls| FileM
    OS -->|FS/Shell calls| Sys
    Net -->|HTTP calls| Web

    Main -->|registers commands| Cmd
    Main -->|registers events| Ev
    Cmd -->|on trigger| Parser
    Ev -->|on event| Parser

    Parser -->|AST + context| FuncGen
    FuncGen -->|internal funcs| IntReg
    FuncGen -->|user funcs| UFMgt
    FuncGen -->|result| Editor

    IntReg --> IMBase
    IntReg --> Conf
    IntReg --> Date
    IntReg --> FileM
    IntReg --> Front
    IntReg --> Hooks
    IntReg --> Sys
    IntReg --> Web

    UFMgt --> UScript
    UFMgt --> USys

    Editor -->|inserts text| Obsd

    Setts -->|governs| Cmd
    Setts -->|governs| Ev
    Setts -->|UI suggesters| FSug
    Setts -->|UI suggesters| FoldSug
    Setts -->|UI suggesters| GenSug

    %% Utils cross-cutting
    Const --> Parser
    Err --> Parser
    Log --> FuncGen
    TJDoc --> FileM
    Utils -->|helpers| FuncGen

    Esb -->|bundles TS| Manif
    Esb -->|generates| Main
    VerUp --> Manif

    %% Click Events
    click Main "https://github.com/silentvoid13/templater/blob/master/src/main.ts"
    click Cmd "https://github.com/silentvoid13/templater/blob/master/src/handlers/CommandHandler.ts"
    click Ev "https://github.com/silentvoid13/templater/blob/master/src/handlers/EventHandler.ts"
    click Sug "https://github.com/silentvoid13/templater/blob/master/src/handlers/FuzzySuggester.ts"
    click Aut "https://github.com/silentvoid13/templater/blob/master/src/editor/Autocomplete.ts"
    click Cur "https://github.com/silentvoid13/templater/blob/master/src/editor/CursorJumper.ts"
    click Mods "https://github.com/silentvoid13/templater/blob/master/src/editor/mode/custom_overlay.js"
    click Mods "https://github.com/silentvoid13/templater/blob/master/src/editor/mode/javascript.js"
    click Editor "https://github.com/silentvoid13/templater/blob/master/src/editor/Editor.ts"
    click Parser "https://github.com/silentvoid13/templater/blob/master/src/core/parser/Parser.ts"
    click FuncGen "https://github.com/silentvoid13/templater/blob/master/src/core/functions/FunctionsGenerator.ts"
    click IntReg "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/InternalFunctions.ts"
    click IMBase "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/InternalModule.ts"
    click Conf "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/config/InternalModuleConfig.ts"
    click Date "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/date/InternalModuleDate.ts"
    click FileM "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/file/InternalModuleFile.ts"
    click Front "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/frontmatter/InternalModuleFrontmatter.ts"
    click Hooks "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/hooks/InternalModuleHooks.ts"
    click Sys "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/system/InternalModuleSystem.ts"
    click Web "https://github.com/silentvoid13/templater/blob/master/src/core/functions/internal_functions/web/InternalModuleWeb.ts"
    click UFMgt "https://github.com/silentvoid13/templater/blob/master/src/core/functions/user_functions/UserFunctions.ts"
    click UScript "https://github.com/silentvoid13/templater/blob/master/src/core/functions/user_functions/UserScriptFunctions.ts"
    click USys "https://github.com/silentvoid13/templater/blob/master/src/core/functions/user_functions/UserSystemFunctions.ts"
    click Setts "https://github.com/silentvoid13/templater/blob/master/src/settings/Settings.ts"
    click Intell "https://github.com/silentvoid13/templater/blob/master/src/settings/RenderSettings/IntellisenseRenderOption.ts"
    click FSug "https://github.com/silentvoid13/templater/blob/master/src/settings/suggesters/FileSuggester.ts"
    click FoldSug "https://github.com/silentvoid13/templater/blob/master/src/settings/suggesters/FolderSuggester.ts"
    click GenSug "https://github.com/silentvoid13/templater/blob/master/src/settings/suggesters/suggest.ts"
    click Const "https://github.com/silentvoid13/templater/blob/master/src/utils/Constants.ts"
    click Err "https://github.com/silentvoid13/templater/blob/master/src/utils/Error.ts"
    click Log "https://github.com/silentvoid13/templater/blob/master/src/utils/Log.ts"
    click TJDoc "https://github.com/silentvoid13/templater/blob/master/src/utils/TJDocFile.ts"
    click Utils "https://github.com/silentvoid13/templater/blob/master/src/utils/Utils.ts"
    click Esb "https://github.com/silentvoid13/templater/blob/master/esbuild.config.mjs"
    click Manif "https://github.com/silentvoid13/templater/blob/master/manifest.json"
    click VerUp "https://github.com/silentvoid13/templater/blob/master/scripts/versions-updater.cjs"

    %% Styles
    classDef host fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef entry fill:#ffe599,stroke:#333,stroke-width:1px;
    classDef handlers fill:#ffd966,stroke:#333,stroke-width:1px;
    classDef core fill:#9fc5e8,stroke:#333,stroke-width:1px;
    classDef modules fill:#b6d7a8,stroke:#333,stroke-width:1px;
    classDef adapter fill:#c9c9ff,stroke:#333,stroke-width:1px;
    classDef support fill:#f2f2f2,stroke:#333,stroke-width:1px;
    classDef build fill:#f9cb9c,stroke:#333,stroke-width:1px;
```
