gRPC Workshop: Go Catalog, Python Checkout

This repo is an LLM-guided, hands-on workshop for getting a practical feel for gRPC. It assumes you already know HTTP/JSON well and have basic Go and Python comfort.

The starting apps are intentionally independent:

• go/ is a product catalog CLI backed by local in-memory data.
• python/ is a checkout CLI backed by its own local in-memory catalog.
• proto/ contains the contract that will make the Python app talk to the Go app.

By the end, the Go app should be a gRPC server and the Python app should be a gRPC client. The Python checkout logic should stay behind the same price lookup boundary.

Start Here

This workshop is driven by an LLM tutor; you only read this README. Open the repo in an editor with an LLM coding agent (Cursor, Claude Code, or similar) that can read files, edit code, and run commands in this workspace. First create a workshop branch (any name) so main stays at the starting state:

git checkout -b workshop

Then paste this prompt:

Be my tutor for this gRPC workshop. Follow AGENTS.md and docs/koans.md. Start me at the beginning, or help me jump ahead if I've already done parts.

The tutor drives from there, one step at a time: it asks you to inspect code, predict behavior, and make the edits yourself, giving hints before code. Keep the editor, terminal, and agent side by side, and let it tutor you rather than dump the final solution. You never need to open docs/koans.md or AGENTS.md; those are the tutor's curriculum and behavior.

Prerequisites

• Go 1.25 or newer.
• Python 3.11 or newer.
• uv.
• make.
• Internet access when running make proto-gen, because it installs gRPC/protobuf generator dependencies.

You do not need a separately installed protoc. The workshop uses grpc_tools.protoc through uv.

Course Shape

The core lab takes about 60-90 minutes with an LLM tutor, depending on how much time you spend with the concept checkpoints.

The core concepts are:

• Proto files define the shared contract.
• Code generation creates client and server shapes in each language.
• Unary RPCs feel like function calls, but deadlines make the network visible.
• gRPC status codes cross service boundaries.
• Application code should translate transport errors into domain errors at the boundary.

The advanced track takes another 30-45 minutes and focuses on production-shaped gRPC skills: inspecting services with grpcurl, enabling gRPC reflection for tooling, and testing real generated clients and servers in-process with bufconn.

Repo Notes

This repo is intentionally unfinished. The initial state should build, run, and test without gRPC dependencies. Python environments and dependencies are managed with uv and locked in python/uv.lock. The gRPC dependencies enter when you start make proto-gen and the client/server koans.

Generated files are ignored by git:

• go/gen/
• python/src/catalog/v1/

The Go module path is github.com/igor-kupczynski/grpc-workshop/go.