# taehoio/protoc-gen-go-ddl architecture

> Architecture diagram of the GitHub repository taehoio/protoc-gen-go-ddl, 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/taehoio/protoc-gen-go-ddl
- Repository: https://github.com/taehoio/protoc-gen-go-ddl

## Overview

##### Project type and purpose
- This is an open‑source CLI tool: a Protocol Buffer compiler plugin written in Go (`protoc-gen-go-ddl`).
- Purpose: read `.proto` definitions and generate Data Definition Language (DDL) SQL statements and Go code stubs (DML interfaces) for supported datastores (currently MySQL, with planned MongoDB etc.).

##### File structure
- Top level:
- `cmd/protoc-gen-marshal-input`: a helper plugin (not the main one).
- `main.go`: entry point for `protoc-gen-go-ddl`.
- `internal/ddl`: core library—parsing protobuf descriptors, building DDL/DML AST, executing templates.
- `internal/ddl/template`: text/template files for SQL and Go code.
- `protos`: versioned `.proto` definitions for the plugin’s own FieldOptions and enums.
- `gen/go`: location of generated Go code when used via Buf or `--go-ddl_out`.
- `testdata`: sample protos and outputs for unit tests.
- `Taskfile.yaml`, `buf.yaml`, `buf.gen.yaml`, and GitHub actions: build, test, generate.
- Patterns & architecture:
- Single executable plugin.
- Separation of concerns:
– CLI layer (`main.go`, `cmd/...`)
– Core logic (`internal/ddl`)
– Codegen templates (`internal/ddl/template`)
– Protobuf definitions for plugin options (`protos/...`)
– Generated artifacts (`gen/`, `testdata/gen/`)
- Configuration & Deployment:
- Go module (`go.mod`, `go.sum`)
- buf plugin config (`buf.gen.yaml`)
- CI config (`.github/workflows/ci.yml`)

##### README for additional insights
- Describes plugin usage via Buf or direct `protoc` CLI.
- Defines supported datastores and data types.
- Illustrates code generation flow: proto → plugin → SQL + Go code.
- Shows DDL output and Go interface stubs for CRUD operations.

##### Detail
- Every logical step: proto parsing, AST creation, template execution.
- How testdata and CI fit in (optional sub‑component).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Inputs
    subgraph "Proto Definitions"
        OptionsProto["Plugin Options (.proto)"]:::proto
        TestProto["Service Test (.proto)"]:::proto
    end
    OptionsProto --> Protoc
    TestProto --> Protoc

    %% Compiler
    Protoc["protoc / buf"]:::cli

    %% Plugin Invocation
    Protoc -->|"calls plugin via gRPC"| Plugin["protoc-gen-go-ddl"]:::cli

    subgraph "CLI Layer"
        Main["Entry Point (main.go)"]:::cli
        Helper["Helper Plugin (cmd/protoc-gen-marshal-input)"]:::cli
    end
    Plugin --> Main
    Plugin --> Helper

    %% Core Library
    subgraph "Core Library (internal/ddl)"
        DDL["Parser & AST (ddl.go)"]:::core
        Field["Field Handling (field.go)"]:::core
        Msg["Message Info (messageinfo.go)"]:::core
        Const["Constants (const.go)"]:::core
    end
    Main --> DDL
    DDL --> Field
    DDL --> Msg
    DDL --> Const

    %% Template Engine
    DDL --> Tmpl
    subgraph "Template Engine"
        Tmpl["Templates Directory"]:::template
    end

    %% Outputs
    Tmpl --> SQL
    Tmpl --> GoCode

    subgraph "Generated Outputs"
        SQL["DDL SQL Files (*.sql)"]:::artifact
        GoCode["Go Code Stubs (*.pb.go)"]:::artifact
    end

    %% Generation Directory
    SQL --> GenOpt
    GoCode --> GenOpt
    SQL --> GenTest
    GoCode --> GenTest

    GenOpt["options.pb.go"]:::artifact
    GenTest["test.pb.go"]:::artifact

    %% Testdata
    subgraph "Testdata"
        TDProtos["testdata/protos/..."]:::artifact
        TDGen["testdata/gen/go/..."]:::artifact
    end

    %% Datastore Targets
    SQL --> MySQL
    SQL --> MongoDB

    subgraph "Datastore Targets"
        MySQL[(MySQL)]:::db
        MongoDB[(MongoDB)]:::db
    end

    %% Click Events
    click Main "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/main.go"
    click Helper "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/cmd/protoc-gen-marshal-input/main.go"
    click DDL "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/internal/ddl/ddl.go"
    click Field "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/internal/ddl/field.go"
    click Msg "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/internal/ddl/messageinfo.go"
    click Const "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/internal/ddl/const.go"
    click Tmpl "https://github.com/taehoio/protoc-gen-go-ddl/tree/main/internal/ddl/template/"
    click OptionsProto "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/protos/taehoio/ddl/protobuf/v1/options.proto"
    click TestProto "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/protos/taehoio/ddl/services/test/v1/test.proto"
    click GenOpt "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/gen/go/taehoio/ddl/protobuf/v1/options.pb.go"
    click GenTest "https://github.com/taehoio/protoc-gen-go-ddl/blob/main/gen/go/taehoio/ddl/services/test/v1/test.pb.go"
    click TDProtos "https://github.com/taehoio/protoc-gen-go-ddl/tree/main/testdata/protos/"
    click TDGen "https://github.com/taehoio/protoc-gen-go-ddl/tree/main/testdata/gen/go/taehoio/ddl/"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#9ff,stroke:#333,stroke-width:1px
    classDef template fill:#ff9,stroke:#333,stroke-width:1px
    classDef artifact fill:#cff,stroke:#333,stroke-width:1px
    classDef db fill:#fcf,stroke:#333,stroke-width:1px
    classDef proto fill:#ccf,stroke:#333,stroke-width:1px
```
