# seamia/protodot architecture

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

- Interactive diagram: https://gitdiagram.com/seamia/protodot
- Repository: https://github.com/seamia/protodot

## Overview

##### Project Type and Purpose
- protodot is a command‐line utility (written in Go) that
- parses Protocol Buffer (`.proto`) files,
- builds an internal representation (AST),
- renders that model via Go templates into Graphviz `.dot` format,

##### File Structure
- Entry point: `main.go` (parses CLI flags, orchestrates flow)
- Configuration: `config.go` + `config.json` (load user options, Graphviz paths)
- Parser & Model: `proto.go`, `payload.go`, `maybe.go` (read & represent `.proto` AST)
- Graph Builder: `graphviz.go`, `table.go`, `support.go` (construct nodes/edges)
- Template Engine:
- `plus/templates.go` and `templates/*.tmpl` (customizable output templates)
- `staticAssets.go` + `assets` (default template set)
- I/O & Utilities: `io.go`, `functions.go`, `debug.go` (file read/write, logging)
- Output & Execution: calls out to Graphviz “dot” tool if configured
- Distribution: `binaries/` (prebuilt executables for multiple platforms, including WebAssembly)

##### Gather Insights from the README
- There is a clear data‐pipeline:
[CLI invocation] → [config load] → [proto parse] → [AST filter/select] → [DOT render via templates] → [write `.dot`] → [optional Graphviz invocation] → [`.svg`/`.png`]
- The tool is highly configurable via a JSON file and template files.

##### Main Components & Their Interactions
a. CLI Interface (main.go)
- Parses flags (`-src`, `-config`, `-select`, etc.)
- Kicks off the pipeline
b. Config Loader (config.go)
- Reads `config.json`—Graphviz locations, output options
- Feeds settings to downstream modules
c. Proto Parser & Model Builder (proto.go, payload.go)
- Uses Go’s I/O routines to parse `.proto`
- Constructs an internal AST/data model (messages, enums, services)
d. Selector/Filter (maybe.go)
- Applies `-select` logic (all, imports, specific elements)
e. Graph Model Builder (graphviz.go, table.go, support.go)
- Converts filtered AST into Graphviz primitives (nodes, edges)
f. Template Engine (plus/templates.go + templates/*.tmpl)
- Renders nodes & edges into `.dot` syntax via text templates
- Users can override templates in `templates/` dir or via `-install`
g. Output Manager & Graphviz Invoker (io.go, staticAssets.go)
- Writes `.dot` output
- If enabled, calls external `dot` binary to generate `.svg`/`.png`
h. Static Assets & Distribution (assets, binaries/)
- Default templates shipped as assets
- Multi-platform binaries, including WASM for online demo

##### Architectural Patterns & Design Principles
- Modular Package Layout: each concern has its own Go file/package
- Pipeline/Chain of Responsibility: data flows through distinct stages
- Template‐Driven Output: separation of logic vs. presentation
- Extensibility: users supply custom templates and configuration
- Cross‐Platform Distribution: prebuilt binaries for various OS/architectures

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Modules"
        direction TB
        CLI["CLI Interface\n(main.go)"]:::input
        ConfigLoader["Config Loader\n(config.go)"]:::input
        ConfigJSON[(config.json)]:::resource
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        direction TB
        ProtoParser["Proto Parser & Model Builder\n(proto.go, payload.go)"]:::core
        Selector["Selector/Filter\n(maybe.go)"]:::core
        GraphBuilder["Graph Model Builder\n(graphviz.go, table.go, support.go)"]:::core
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        direction TB
        TemplateEngine["Template Engine\n(plus/templates.go)"]:::render
        TemplatesFolder["Templates Folder\n(templates/*.tmpl)"]:::resource
    end

    %% Output Layer
    subgraph "Output & External"
        direction TB
        OutputManager["Output Manager\n(io.go, staticAssets.go)"]:::output
        GraphvizTool["Graphviz Tool (dot)"]:::external
        AssetsDir["Assets Directory\n(assets/)"]:::resource
        BinariesDir["Prebuilt Binaries\n(binaries/)"]:::resource
    end

    %% Data Flow
    CLI -->|"flags"| ConfigLoader
    ConfigLoader -->|"loads settings"| ConfigJSON
    ConfigLoader --> ProtoParser
    ProtoParser -->|"AST"| Selector
    Selector -->|"Filtered AST"| GraphBuilder
    GraphBuilder -->|"Graph Model"| TemplateEngine
    TemplateEngine -->|".dot syntax"| OutputManager
    OutputManager -->|"writes .dot"| AssetsDir
    OutputManager -->|"invokes dot"| GraphvizTool
    GraphvizTool -->|".svg/.png"| AssetsDir
    AssetsDir --> BinariesDir

    %% Click Events
    click CLI "https://github.com/seamia/protodot/blob/master/main.go"
    click ConfigLoader "https://github.com/seamia/protodot/blob/master/config.go"
    click ConfigJSON "https://github.com/seamia/protodot/blob/master/config.json"
    click ProtoParser "https://github.com/seamia/protodot/blob/master/proto.go"
    click ProtoParser "https://github.com/seamia/protodot/blob/master/payload.go"
    click Selector "https://github.com/seamia/protodot/blob/master/maybe.go"
    click GraphBuilder "https://github.com/seamia/protodot/blob/master/graphviz.go"
    click GraphBuilder "https://github.com/seamia/protodot/blob/master/table.go"
    click GraphBuilder "https://github.com/seamia/protodot/blob/master/support.go"
    click TemplateEngine "https://github.com/seamia/protodot/blob/master/plus/templates.go"
    click TemplatesFolder "https://github.com/seamia/protodot/tree/master/templates/"
    click OutputManager "https://github.com/seamia/protodot/blob/master/io.go"
    click OutputManager "https://github.com/seamia/protodot/blob/master/staticAssets.go"
    click AssetsDir "https://github.com/seamia/protodot/tree/master/assets/"
    click BinariesDir "https://github.com/seamia/protodot/tree/master/binaries/"

    %% Styles
    classDef input fill:#a8e6cf,stroke:#1a9c70,color:#000
    classDef core fill:#dcedc1,stroke:#6b8e23,color:#000
    classDef render fill:#fff5ba,stroke:#e6c229,color:#000
    classDef output fill:#ffccbc,stroke:#ff7043,color:#000
    classDef external fill:#eceff1,stroke:#78909c,color:#000
    classDef resource fill:#e0f7fa,stroke:#00acc1,color:#000
```
