# google/dotprompt architecture

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

- Interactive diagram: https://gitdiagram.com/google/dotprompt
- Repository: https://github.com/google/dotprompt

## Overview

##### Project type and purpose
- Dotprompt is an open-source, multi-language SDK and tooling suite for “executable GenAI prompt templates.”
- It defines a file format (.prompt / YAML frontmatter + Handlebars) plus a core specification, and provides language-specific implementations (Go, JavaScript/TypeScript, Python, Java, Rust), a test harness, documentation site, and CI/CD scaffolding.

##### File structure
- Top-level: Bazel configs, GitHub workflows, language directories (go/, js/, python/, java/, rs/), core specification (spec/), third-party docsite (Astro), build/test scripts (scripts/), and CI config.
- spec/: YAML definitions of picoschema and template specification → the canonical format.
- go/, js/, python/, java/, rs/: each contains source, tests, build configs, adapters.
- third_party/docsite/: static site generator for docs and examples.
- scripts/: automation helpers for linting, building, testing, formatting, and release.
- CI workflows trigger on changes to each language, spec, docs, and publish packages.

##### README for additional insights
- Describes the core concept: executable prompt templates include metadata (model, input schema, output schema) + templating engine.
- Shows example usage in JavaScript via Genkit plugin.
- Mentions extensibility via implementations for other languages and providers (openai, gemini).

##### Elements
- Clear labels for each component (e.g., “Core Spec,” “Runtime Engine,” “Go SDK,” “OpenAI Adapter,” “Docsite”)
- .prompt file → Runtime Engine → Adapter → Model Provider → Runtime Engine → SDK → User code
- spec/ → SDKs and Docsite
- scripts/ → CI pipelines
- Adapters / external services (e.g., green)
- Docs & CI (e.g., grey)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Specification
    subgraph "Core Specification" 
        direction TB
        SpecFolder["spec/"]:::core
        Picoschema["picoschema.yaml"]:::core
        Metadata["metadata.yaml"]:::core
        Partials["partials.yaml"]:::core
        HelpersSpec["helpers/"]:::core
        SchemaJson["schema.json"]:::core
        Variables["variables.yaml"]:::core
        SpecFolder --> Picoschema
        SpecFolder --> Metadata
        SpecFolder --> Partials
        SpecFolder --> HelpersSpec
        SpecFolder --> SchemaJson
        SpecFolder --> Variables
    end

    %% Language SDKs
    subgraph "Language SDKs"
        direction TB
        subgraph "Go SDK" 
            direction TB
            GoEngine["Go Runtime Engine"]:::sdk
        end
        subgraph "JS/TS SDK"
            direction TB
            JSEngine["JS/TS Runtime Engine"]:::sdk
        end
        subgraph "Python SDK"
            direction TB
            PyEngine["Python Runtime Engine"]:::sdk
            PyAdapterOpt["OpenAI Adapter"]:::adapter
        end
        subgraph "Java SDK"
            direction TB
            JavaEngine["Java Runtime Engine"]:::sdk
        end
        subgraph "Rust SDK"
            direction TB
            RustEngine["Rust Smoke Tests"]:::sdk
        end
    end

    %% Adapters & External Services
    subgraph "Adapters & Providers"
        direction TB
        OpenAI["OpenAI API"]:::external
        Gemini["Gemini API"]:::external
    end

    %% Documentation & CI
    subgraph "Docs & CI Infrastructure"
        direction TB
        Docsite["Documentation Site"]:::infra
        Scripts["scripts/"]:::infra
        Workflows[".github/workflows/"]:::infra
    end

    %% User Interaction
    PromptFile[".prompt File"]:::external
    UserApp["User Application"]:::external

    %% Relationships
    PromptFile -->|loads spec| SpecFolder
    PromptFile -->|runs via| GoEngine
    PromptFile -->|runs via| JSEngine
    PromptFile -->|runs via| PyEngine
    PromptFile -->|runs via| JavaEngine
    PromptFile -->|runs via| RustEngine

    SpecFolder -->|feeds| GoEngine
    SpecFolder -->|feeds| JSEngine
    SpecFolder -->|feeds| PyEngine
    SpecFolder -->|feeds| JavaEngine
    SpecFolder -->|feeds| RustEngine

    GoEngine -->|invokes| OpenAI
    JSEngine -->|invokes| OpenAI
    PyEngine -->|invokes| PyAdapterOpt
    PyEngine -->|invokes| Gemini
    JavaEngine -->|invokes| OpenAI
    RustEngine -->|invokes| Gemini

    OpenAI -->|returns output| GoEngine
    OpenAI -->|returns output| JSEngine
    OpenAI -->|returns output| JavaEngine
    Gemini -->|returns output| PyEngine
    Gemini -->|returns output| RustEngine

    GoEngine -->|returns result| UserApp
    JSEngine -->|returns result| UserApp
    PyEngine -->|returns result| UserApp
    JavaEngine -->|returns result| UserApp
    RustEngine -->|returns result| UserApp

    SpecFolder -->|used by| Docsite
    JSEngine -->|examples to| Docsite
    GoEngine -->|examples to| Docsite
    PyEngine -->|examples to| Docsite
    JavaEngine -->|examples to| Docsite
    RustEngine -->|examples to| Docsite

    Scripts -->|automate| GoEngine
    Scripts -->|automate| JSEngine
    Scripts -->|automate| PyEngine
    Scripts -->|automate| JavaEngine
    Scripts -->|automate| RustEngine
    Workflows -->|trigger tests| Scripts
    Workflows -->|trigger builds| Scripts

    %% Click Events
    click SpecFolder "https://github.com/google/dotprompt/tree/main/spec/"
    click Picoschema "https://github.com/google/dotprompt/blob/main/spec/picoschema.yaml"
    click Metadata "https://github.com/google/dotprompt/blob/main/spec/metadata.yaml"
    click Partials "https://github.com/google/dotprompt/blob/main/spec/partials.yaml"
    click HelpersSpec "https://github.com/google/dotprompt/tree/main/spec/helpers/"
    click SchemaJson "https://github.com/google/dotprompt/blob/main/spec/schema.json"
    click Variables "https://github.com/google/dotprompt/blob/main/spec/variables.yaml"

    click GoEngine "https://github.com/google/dotprompt/blob/main/go/dotprompt/dotprompt.go"
    click GoEngine "https://github.com/google/dotprompt/blob/main/go/dotprompt/parse.go"
    click GoEngine "https://github.com/google/dotprompt/blob/main/go/dotprompt/picoschema.go"
    click GoEngine "https://github.com/google/dotprompt/blob/main/go/dotprompt/helper.go"
    click GoEngine "https://github.com/google/dotprompt/blob/main/go/dotprompt/util.go"

    click JSEngine "https://github.com/google/dotprompt/blob/main/js/src/dotprompt.ts"
    click JSEngine "https://github.com/google/dotprompt/blob/main/js/src/parse.ts"
    click JSEngine "https://github.com/google/dotprompt/blob/main/js/src/picoschema.ts"
    click JSEngine "https://github.com/google/dotprompt/blob/main/js/src/helpers.ts"
    click JSEngine "https://github.com/google/dotprompt/blob/main/js/src/util.ts"
    click JSEngine "https://github.com/google/dotprompt/blob/main/js/src/index.ts"

    click PyEngine "https://github.com/google/dotprompt/blob/main/python/dotpromptz/src/dotpromptz/dotprompt.py"
    click PyEngine "https://github.com/google/dotprompt/blob/main/python/dotpromptz/src/dotpromptz/parse.py"
    click PyEngine "https://github.com/google/dotprompt/blob/main/python/dotpromptz/src/dotpromptz/picoschema.py"
    click PyEngine "https://github.com/google/dotprompt/blob/main/python/dotpromptz/src/dotpromptz/helpers.py"
    click PyEngine "https://github.com/google/dotprompt/blob/main/python/dotpromptz/src/dotpromptz/util.py"
    click PyAdapterOpt "https://github.com/google/dotprompt/blob/main/python/dotpromptz/src/dotpromptz/adapters/openai.py"
    click PyEngine "https://github.com/google/dotprompt/tree/main/python/dotpromptz/src/dotpromptz/stores/"

    click JavaEngine "https://github.com/google/dotprompt/blob/main/java/com/google/dotprompt/BUILD.bazel"
    click JavaEngine "https://github.com/google/dotprompt/blob/main/java/com/google/dotprompt/smoke/Smoke.java"
    click JavaEngine "https://github.com/google/dotprompt/blob/main/java/com/google/dotprompt/smoke/SmokeTest.java"

    click Docsite "https://github.com/google/dotprompt/blob/main/third_party/docsite/astro.config.mjs"
    click Docsite "https://github.com/google/dotprompt/tree/main/third_party/docsite/src/"
    click Docsite "https://github.com/google/dotprompt/tree/main/third_party/docsite/src/content/"
    click Docsite "https://github.com/google/dotprompt/tree/main/third_party/docsite/src/components/"
    click Docsite "https://github.com/google/dotprompt/tree/main/third_party/docsite/src/pages/"

    click Scripts "https://github.com/google/dotprompt/tree/main/scripts/"
    click Workflows "https://github.com/google/dotprompt/tree/main/.github/workflows/"

    click RustEngine "https://github.com/google/dotprompt/blob/main/rs/smoke/Cargo.toml"
    click RustEngine "https://github.com/google/dotprompt/blob/main/rs/smoke/src/lib.rs"
    click RustEngine "https://github.com/google/dotprompt/blob/main/rs/smoke/BUILD.bazel"
    
    %% Styles
    classDef core fill:#D0E6FF,stroke:#4A90E2,stroke-width:2px
    classDef sdk fill:#FFE5B4,stroke:#FF8C00,stroke-width:2px
    classDef adapter fill:#D4F4DD,stroke:#2E8B57,stroke-width:2px
    classDef external fill:#F2F2F2,stroke:#999999,stroke-width:1px,stroke-dasharray: 2 2
    classDef infra fill:#E5E5E5,stroke:#666666,stroke-width:2px
    class SpecFolder,Picoschema,Metadata,Partials,HelpersSpec,SchemaJson,Variables core
    class GoEngine,JSEngine,PyEngine,JavaEngine,RustEngine sdk
    class PyAdapterOpt adapter
    class OpenAI,Gemini external
    class PromptFile,UserApp external
    class Docsite,Scripts,Workflows infra
```
