Explorer

Interactive protobuf schema explorer for evalops/proto.

Two graph views, full-text search, and drill-down detail panels — all from a single Go binary with zero runtime dependencies.

Quick Start

Prerequisites: Go 1.22+

git clone https://github.com/evalops/explorer.git
cd explorer
go build -o explorer .
./explorer -proto /path/to/evalops/proto
# open http://localhost:8080

Or with go run:

go run . -proto ../proto -port 9090

Views

Architecture

Packages and their consuming services laid out with cose-bilkent. Click a package to see its services, messages, enums, and downstream consumers. Edges show which services import which proto packages.

API

Hierarchical dagre layout showing the full RPC surface: services contain methods, methods connect to their request and response message types, and cross-reference edges link messages that embed other messages as fields.

Features

• Proto parsing — reads .proto files directly with a built-in text parser (no protoc or buf installation required)
• Consumer discovery — extracts the package-to-consumer mapping from the proto repo README.md markdown table
• Full-text search — search across packages, services, RPC methods, messages, fields, enums, and enum values; press / to focus
• Detail panel — field tables with type annotations (repeated, optional, map), clickable type cross-references, and "used by" tracking showing which RPCs consume each message
• Graph interaction — click any node to highlight its neighborhood and fade unrelated nodes; pan, zoom, and fit controls
• Hot reload — click the reload button or hit /api/reload to re-parse proto files without restarting the server

Flags

Flag	Default	Description
-proto	.	Path to the proto repository root (the directory containing proto/ and README.md)
-port	8080	HTTP server port

How It Works

Backend (Go, stdlib only)

The backend walks the proto/ directory, parses each .proto file with a line-by-line recursive descent parser, and aggregates results into packages. It handles services, RPC methods (including streaming), messages (including nested), enums, oneofs, map fields, and leading comments. It also parses the README.md markdown table to extract which services consume each package.

Four JSON endpoints power the frontend:

Endpoint	Description
GET /api/schema	Full parsed schema — all packages with their services, messages, and enums
GET /api/graph/architecture	Cytoscape elements for the package-to-consumer graph
GET /api/graph/api	Cytoscape elements for the service-to-method-to-message graph
GET /api/search?q=...	Case-insensitive full-text search across all types
POST /api/reload	Re-parse proto files from disk

Frontend (vanilla JS + Cytoscape.js)

The frontend is a single-page app served as static files from the Go binary. No build step, no npm, no bundler.

• Cytoscape.js for graph rendering and interaction
• cytoscape-cose-bilkent for force-directed architecture layout
• cytoscape-dagre for hierarchical API layout
• Graceful fallback to built-in cose and breadthfirst layouts if CDN plugins are unavailable

What it parses

The parser extracts the full structure from proto3 files:

• syntax, package, import declarations
• service definitions with rpc methods (unary and streaming)
• message definitions with fields, nested messages, oneofs, and map fields
• enum definitions with values
• Leading // comments attached to the next declaration
• Field modifiers: repeated, optional, map<K, V>
• Field numbers for wire format reference

Compatibility with protoc and buf

Explorer reads .proto source files directly and does not invoke protoc or buf. This means:

• No toolchain required — works anywhere Go runs
• No import resolution — well-known types like google.protobuf.Timestamp are recognized by name but not followed into their definitions
• No custom options — proto options beyond go_package are skipped

If you need full descriptor-level fidelity (custom options, source info, full import graphs), you can extend the backend to parse buf build -o image.binpb output using google.golang.org/protobuf/types/descriptorpb instead of the text parser.

Project Layout

go.mod          Go module
main.go         HTTP server, API handlers, README parser
model.go        Data model types (Package, Service, Message, etc.)
parser.go       Proto file text parser and directory walker
frontend/
  index.html    Single-page app shell
  style.css     Dark theme styles
  app.js        Cytoscape graph, detail panel, search

Related

• evalops/proto — the proto definitions this tool explores
• buf.build — the schema registry and toolchain used by the proto repo
• Cytoscape.js — the graph visualization library powering the frontend