# pkg

Shared wire contracts for the Scrabble platform (module `scrabble/pkg`),
imported by both `backend` and `gateway`. It carries no logic — only the
generated message types and the schemas they come from.

## Layout

```
proto/push/v1/    # backend -> gateway live-event gRPC channel (Push.Subscribe)
                  #   committed generated Go (*.pb.go, *_grpc.pb.go)
fbs/scrabble.fbs  # FlatBuffers edge payloads (one `scrabblefb` namespace)
fbs/scrabblefb/   # committed generated Go for the schema
```

- **`proto/push/v1`** is the single gRPC server-stream the backend exposes and
  the gateway subscribes to (`Event{user_id, kind, payload, event_id}`); the
  `payload` is an opaque FlatBuffers body the gateway forwards verbatim.
- **`proto/telegram/v1`** is the Telegram connector's RPC contract (Stage 9; Stage 11
  added `ValidateLoginWidget` for the web Login Widget sign-in).
- **`fbs`** holds the client↔gateway request/response and event payloads as
  FlatBuffers tables. The backend encodes the push payloads from these types; the
  gateway transcodes the rest to and from the backend's JSON; the UI generates
  TypeScript from the same `.fbs` (Stage 7).

## Generated code

Committed (CI only builds it); regenerate dev-time after editing the schemas:

```sh
make -C pkg tools   # go install protoc-gen-go + protoc-gen-go-grpc
make -C pkg gen     # buf generate (proto) + flatc (fbs)
```

`flatc` is pinned to **23.5.26** to match the `github.com/google/flatbuffers`
Go runtime in `go.mod`; generating with another version is refused.

## Workspace wiring

`scrabble/pkg` is a bare-path module (no dot), so — like `scrabble-solver` — it
cannot be fetched as a versioned dependency. `go.work` carries `use ./pkg` and
`replace scrabble/pkg v0.0.0 => ./pkg`; consumers `require scrabble/pkg v0.0.0`.