Terms and Concepts

This page defines the terms ProtoMap uses in the platform, the CLI, and these docs.

The Graph

ProtoMap builds a graph of your gRPC services from your scans. It is made of five kinds of items, each with its own color in the platform:

Item	What it is
Repository	A Git repository you scanned. Every clone of a repository shares one identity, from its origin remote.
Service	A gRPC service, such as hipstershop.CheckoutService, declared in a .proto file.
Method	An RPC of a service, such as CheckoutService/PlaceOrder, with its request and response messages.
Message	A protobuf message, such as PlaceOrderRequest.
Field	A field of a message, such as PlaceOrderRequest.user_id.

Services, methods, messages, and fields go by their fully qualified protobuf names, so repositories that declare the same name declare the same item, such as a .proto file copied into several repositories.

Code

Term	Meaning
Handler	The code that implements a method: what runs when the method is called.
Call site	A place in the code that calls a method, through a generated client or otherwise.
Caller	A service or method whose code calls another. Its callees are the services and methods it calls.
Dependent	Anything that depends on an item, directly or through other services. Its dependencies are what it depends on.
Program	Code that calls gRPC services without implementing one, such as a command-line tool or a batch job.
Maintainers	The people who wrote and committed a service’s protobuf definition and gRPC code, from Git history.

ProtoMap links call sites to handlers by the method’s name. Your deployment is not known to ProtoMap, so when several repositories implement the same method, a call site links to each of them.

Flows

A flow is the path a protobuf field takes through your code: from where a service receives it, such as a request field, to where it sends it on, such as a field of a request to another service, or of its response. Flows continue across services, so you can follow a field from one service into the next.

The blast radius of a change is everything it can affect: the callers of a method, the services that send or receive a field, and the call sites that use them.

Certainty

ProtoMap favors recall: it keeps a call or flow it cannot rule out, and marks it uncertain, rather than drop it. Typical reasons are a method name built from a string, or a call through an interface that several types implement.

A graph review by an AI provider judges how likely each uncertain flow is to be real, shown as a percentage on the flow.

Scans

Term	Meaning
Scan	One run of the CLI over one repository at one revision. The result uploads to your ProtoMap Server.
Primary branch	The branch whose scans join the shared graph, by default the remote’s default branch, such as main.
Shared graph	What everyone in the organization sees: for each repository, the latest pushed commit on its primary branch, with no uncommitted changes.
Private scan	Any other scan, such as of uncommitted changes or another branch. Only the person who ran it sees it, laid over the shared graph.

See Scanning for the exact rules.

Organizations and Roles

An organization holds its repositories, scans, chats, and users. Each user has a role in it — Owner, Admin, Write, or Read — that decides what they can do. A self-hosted server also has server owners, who manage the server itself. See Users and Roles.