# moul/protoc-gen-gotemplate architecture

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

- Interactive diagram: https://gitdiagram.com/moul/protoc-gen-gotemplate
- Repository: https://github.com/moul/protoc-gen-gotemplate

## Overview

##### Project Type and Purpose
- This is an **open‑source code generation tool / protoc plugin** (“protoc‑gen‑gotemplate”).
- It plugs into the `protoc` compiler, reads `.proto` files, constructs an AST (via `protoc-gen-go` helpers), and then applies user‑supplied Go text‑templates to generate code, scripts, or data files.
- It also ships an optional **Web Editor** (in `cmd/web-editor`) that lets you play with `.proto` + template pairs in your browser.

##### Key Architectural Components
A. External Tools and Inputs
- `protoc` (Google’s Protobuf compiler) – invokes the plugin
- `.proto` source files & user templates directory
B. Plugin CLI (`main.go`, helpers/, vendor/)
1. **CLI Entrypoint** (root `main.go` + `Makefile` + Dockerfile)
- Parses plugin‑specific flags (template_dir, destination_dir, debug, single‑package‑mode, etc.)
- Invoked by `protoc --gotemplate_out=…`
2. **AST Builder**
- Leverages `protoc-gen-go` helper functions to transform `.proto` descriptors into an internal AST
3. **Template Engine**
- Loads every `*.tmpl` in the template directory (preserving subfolders)
- Constructs a funcmap: combines Sprig helpers + custom helpers in `helpers/` (e.g., `goType`, `camelCase`, `httpPath`, etc.)
- For each AST + template, executes `text/template` to emit output files
4. **Output Writer**
- Maps the template sub‑path to the target file path (drops the `.tmpl` extension) under `destination_dir`
C. Web Editor (`cmd/web-editor/`)
- A small HTTP server serving `static/index.html`
- Loads the same plugin core as a library to process user input in real time
- Provides a browser UI for live generation demos
D. Containerization & CI
- `Dockerfile` / GitHub Actions workflows build / test / release the plugin image on Docker Hub
- `Makefile` and `.releaserc.js` automate versioning and publishing

##### Relationships and Data Flows
- Directional flow:
[protoc] ──> [protoc‑gen‑gotemplate CLI] ──> (parses flags, loads `.proto`)
└─> [AST Builder] ──> [Template Engine (+ FuncMap)] ──> [Output Writer] ──> generated files
- Web Editor path:
[Browser] ↔ HTTP ↔ [Web‑Editor Server] ↔ Plugin Core → on‑the‑fly generation
- Docker wraps the CLI entrypoint, mounting the project directory and invoking the plugin inside a container.

##### Architectural Patterns & Design Principles
- **Plugin Architecture**: conforms to the `protoc` plugin interface
- **Modular Layers**: CLI → AST → Template Engine → I/O
- **Separation of Concerns**: core generator is decoupled from the Web UI
- **Extensibility**: user‑supplied templates + funcmap enable custom output formats

- `protoc` ➔ plugin CLI ➔ AST Builder ➔ Template Engine ➔ File System
- Browser ↔ HTTP Server ↔ plugin core
- External dependencies (green)
- Core modules (blue)
- Data stores / file I/O (gray)
- Network layer (orange for HTTP)
- Annotations for key **technologies**: Go, text/template, Sprig, protoc-gen-go, Docker

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Tools
    subgraph "External Tools"
        protoc["protoc"]:::external
        protoFiles[".proto files & templates"]:::data
    end

    %% Core Plugin CLI
    subgraph "Plugin CLI (Core)"
        parser["CLI Parser\n(flags: template_dir, debug, single_package_mode)"]:::process
        ast["AST Builder"]:::process
        funcmap["FuncMap Loader\n(Sprig + custom)"]:::process
        tmpl["Template Engine\n(text/template)"]:::process
        writer["Output Writer\n(.tmpl ➔ generated file)"]:::process
    end

    %% Data Stores
    output["Generated files"]:::data

    %% Web Editor
    subgraph "Web Editor"
        browser["Browser"]:::network
        webserver["Web Editor Server\nHTTP Server"]:::network
        static["UI (static/index.html)"]:::network
    end

    %% Container & CI
    subgraph "Container & CI"
        docker["Docker Image"]:::external
        workflows["GitHub Actions CI"]:::external
        releaseCfg["Release Config\n(.releaserc.js)"]:::external
    end

    %% Relationships
    protoFiles --> protoc
    protoc --> parser
    parser --> ast
    ast --> funcmap
    funcmap --> tmpl
    tmpl --> writer
    writer --> output

    browser <--> webserver
    webserver --> parser

    docker --> parser
    workflows --> docker
    releaseCfg -.-> workflows

    %% Click Events
    click parser "https://github.com/moul/protoc-gen-gotemplate/blob/master/main.go"
    click parser "https://github.com/moul/protoc-gen-gotemplate/tree/master/Makefile"
    click parser "https://github.com/moul/protoc-gen-gotemplate/tree/master/Dockerfile"
    click ast "https://github.com/moul/protoc-gen-gotemplate/tree/master/vendor/github.com/golang/protobuf/protoc-gen-go/plugin"
    click funcmap "https://github.com/moul/protoc-gen-gotemplate/blob/master/helpers/custom_options.go"
    click funcmap "https://github.com/moul/protoc-gen-gotemplate/blob/master/helpers/encoders.go"
    click funcmap "https://github.com/moul/protoc-gen-gotemplate/blob/master/helpers/helpers.go"
    click funcmap "https://github.com/moul/protoc-gen-gotemplate/blob/master/helpers/parameters.go"
    click writer "https://github.com/moul/protoc-gen-gotemplate/blob/master/main.go"
    click webserver "https://github.com/moul/protoc-gen-gotemplate/blob/master/cmd/web-editor/main.go"
    click static "https://github.com/moul/protoc-gen-gotemplate/blob/master/cmd/web-editor/static/index.html"
    click docker "https://github.com/moul/protoc-gen-gotemplate/tree/master/Dockerfile"
    click docker "https://github.com/moul/protoc-gen-gotemplate/blob/master/.dockerignore"
    click workflows "https://github.com/moul/protoc-gen-gotemplate/blob/master/.github/workflows/go.yml"
    click workflows "https://github.com/moul/protoc-gen-gotemplate/blob/master/.github/workflows/pr.yml"
    click workflows "https://github.com/moul/protoc-gen-gotemplate/blob/master/.github/workflows/release.yml"
    click releaseCfg "https://github.com/moul/protoc-gen-gotemplate/blob/master/.releaserc.js"

    %% Styles
    classDef external fill:#ccffcc,stroke:#006600,color:#003300
    classDef process fill:#cce5ff,stroke:#003366,color:#001933
    classDef data fill:#e6e6e6,stroke:#666666,color:#333333
    classDef network fill:#ffd9b3,stroke:#cc6600,color:#663300
```
