Lesson 1 · Foundations

What gRPC is, and why it exists

Call a method on another server as if it were local.

Your win: explain in one breath what gRPC is, why it's built on Protocol Buffers + HTTP/2, and why every internal call in your monorepo uses it instead of hand-rolled REST.

The problem: services need to call each other

spike needs media info from notification. conversationmgmt needs config from mastermgmt. The naive way is REST + JSON over HTTP/1.1: hand-write URLs, marshal JSON, hope both sides agree on the shape. Nothing enforces the contract, JSON is chatty, and HTTP/1.1 opens a connection per call. At 30+ services, that friction compounds.

gRPC's answer: a generated, typed remote call

gRPC lets a client call a method on a server on another machine as if it were a local object.¹ You declare the service once in a .proto contract; a generator produces a typed client and server; you just call the method. Two technologies make it work:

Protocol Buffers

The contract + payload format — a strict, versionable IDL that serializes to compact binary. Typed on both ends. (Lesson 2.)

HTTP/2

The transport — one long-lived connection multiplexing many concurrent streams, with header compression. Efficient, and it's what enables streaming. (Part 2.)

The one-liner gRPC = define a service in Protobuf, generate client + server, call remote methods like local ones — over HTTP/2. The contract is enforced by codegen, so the two services can't silently disagree.

Your code already lives this

Every internal call in the monorepo is gRPC. When spike needs media, it doesn't build an HTTP request — it calls a generated method on a client stub:

internal/spike/modules/email/application/media_manager/media_info_fetcher.go:24

// A remote call to the notification service — looks like a local method:
resp, err := f.client.InternalRetrieveMedia(ctx, &npb.InternalRetrieveMediaRequest{
    MediaIds: mediaIDs, OrganizationId: org.OrganizationID().String(),
})

Anchor f.client is a generated npb.MediaReaderServiceClient; spike dialed notification at startup (rsc.GRPCDial("notificationmgmt")). The request/response types (npb.*) came from notification's .proto. No URLs, no JSON — just a typed method call. Full map: repo-grpc-map.md.

gRPC vs REST — the 10-second version

Rule of thumb (full comparison in Part 5): gRPC for internal service-to-service (typed, fast, streaming), REST/JSON for public or browser-facing APIs (universal, human-readable). Our repo does both — it even exposes some gRPC services as REST via a gateway (Part 5).

gRPC — "What is gRPC? Introduction" + Core concepts

The official framing (call remote as local; why Protobuf + HTTP/2), then the core concepts page that anchors the rest of this course.

→ grpc.io/docs/what-is-grpc/introduction
→ grpc.io — core concepts

Check yourself (from memory)

Q1. gRPC lets a client call a remote method…

The generated stub makes a remote method look local — that's the whole pitch. spike's InternalRetrieveMedia call is one.

Q2. By default, gRPC's contract/IDL is…

Protobuf is both the interface definition language and the compact binary wire format.

Q3. gRPC runs on which transport?

HTTP/2 — one connection, many multiplexed streams, header compression. It's what makes streaming (Part 2) possible.

In one sentence: what is gRPC, and what two technologies underpin it?

recall, then click to reveal

gRPC is a framework for calling a method on a remote server as if it were local, defined by a Protocol Buffers contract (typed, compact binary) and carried over HTTP/2 (one connection, many multiplexed streams, header compression). In our repo, every internal service-to-service call is gRPC.

Want the deeper "why HTTP/2 specifically" (multiplexing, no head-of-line blocking)? Ask me. I'm your teacher for this course.

1. gRPC — Introduction; Core concepts.