# gRPC Resources

Curated, high-trust sources for this workspace. Explainers in the lessons draw from here
— not from memory. Grouped **Knowledge** (learn the ideas), **Wisdom** (communities), and
**Repo** (our own code, the ground truth for this mission).

## Knowledge

### Start here (official, conceptual)
- [What is gRPC? — Introduction](https://grpc.io/docs/what-is-grpc/introduction/)
  The one-page "call a method on another machine as if it were local" framing, plus why
  Protocol Buffers + HTTP/2. **Use for:** the first pass on the whole idea.
- [gRPC — Core concepts, architecture & lifecycle](https://grpc.io/docs/what-is-grpc/core-concepts/)
  The authoritative description of the **four RPC types**, the RPC lifecycle, deadlines,
  cancellation, and metadata. **Use for:** almost every lesson — this is the backbone.

### Protocol Buffers (the contract)
- [Protocol Buffers — Language Guide (proto3)](https://protobuf.dev/programming-guides/proto3/)
  The definitive guide to messages, scalar types, field numbers, enums, and services.
  **Use for:** the "write a .proto" lessons and the field-number/wire rules.
- [Protobuf — proto3 spec](https://protobuf.dev/reference/protobuf/proto3-spec/)
  The exact grammar when a lesson needs precision. **Use for:** edge cases.

### Go implementation + codegen (matches our stack)
- [gRPC — Go Quick start](https://grpc.io/docs/languages/go/quickstart/) ·
  [Go Basics tutorial](https://grpc.io/docs/languages/go/basics/)
  Build a Go gRPC service end-to-end, including all four method types. **Use for:**
  hands-on after each concept lesson.
- [`grpc-go` — GitHub](https://github.com/grpc/grpc-go) ·
  [pkg.go.dev/google.golang.org/grpc](https://pkg.go.dev/google.golang.org/grpc)
  The library our services use. **Use for:** server/client options, interceptors, status,
  metadata APIs.
- [gRPC Go — protoc plugins](https://grpc.io/docs/languages/go/quickstart/#prerequisites)
  (`protoc-gen-go`, `protoc-gen-go-grpc`) — **this repo generates with raw `protoc`**,
  driven by `make gen-proto-go` → `proto/gen_go.sh` (Docker Compose), **not**
  `buf generate`. **Use for:** understanding the actual codegen step.
- [Buf docs](https://buf.build/docs/) — in this repo `buf` is used for **linting &
  breaking-change checks only** (`proto/buf.yaml`, `make lint-proto`), not codegen. **Use
  for:** proto style/compatibility rules.

### Guides for the specific pillars
- [gRPC Guides — index](https://grpc.io/docs/guides/) — authoritative how-tos for
  **error handling**, **deadlines**, **cancellation**, **metadata**, **interceptors**,
  **authentication**, and **load balancing**. **Use for:** Parts 3–5. Each guide is the
  primary source for its lesson.

### Book (deep dive)
- [_gRPC: Up and Running_ — Kasun Indrasiri & Danesh Kuruppu (O'Reilly)](https://www.oreilly.com/library/view/grpc-up-and/9781492058328/)
  Go + Java, from basics to production (LB, security, observability). **Use for:** a
  chapter after the matching lesson when you want more depth.

## Wisdom (Communities)
- [grpc.io community / grpc-io mailing list](https://groups.google.com/g/grpc-io)
  The upstream community. **Use for:** authoritative answers on gRPC behaviour.
- [r/grpc](https://www.reddit.com/r/grpc/) and [r/golang](https://www.reddit.com/r/golang/)
  **Use for:** real-world design questions, "is this idiomatic?", interview threads.
- [Buf Slack](https://buf.build/docs/community/) **Use for:** proto/buf tooling questions.

## Repo (ground truth for this mission)
Our own gRPC usage — proto layout, server setup, the interceptor chain, RBAC, and the
four RPC types across our services — is captured in
[reference/repo-grpc-map.md](./reference/repo-grpc-map.md) (generated from a scan of
`internal/notification`, `internal/spike`, conversationmgmt, `internal/golibs`, and `proto/`).
The repo also has per-endpoint API docs under `docs/{service}/{module}/{Method}.md`.

## Gaps
- No single trusted gRPC interview-question bank listed — quality varies. Lessons build
  their own recall quizzes from the authoritative sources above.
- HTTP/2 depth: the grpc.io intro explains the "why"; if the mission needs framing/flow
  control detail, add an HTTP/2 primary source then.