go-micro-kit

---
name: go-micro-kit
description: Use when building, modifying, or debugging Go microservices with github.com/updevru/go-micro-kit, including protobuf-first gRPC services, gRPC-Gateway HTTP APIs, env configuration, OpenTelemetry setup, GORM/PostgreSQL migrations, cron tasks, Consul discovery, Swagger UI, and service bootstrap wiring.
license: Apache-2.0
---

# go-micro-kit

Use this skill as the project-specific guide for `github.com/updevru/go-micro-kit`. Prefer the framework's packages and conventions when the user asks to scaffold or change a Go microservice that uses this kit.

## First Steps

Inspect the target service before editing:

1. Read `go.mod` to confirm the module path and `github.com/updevru/go-micro-kit` version.
2. Read `main.go` or `cmd/**/main.go` to see how the bootstrap manager is wired.
3. Read `internal/config`, `.env.example`, or deployment env files before changing configuration.
4. Read `proto/`, `gen/`, and `docs/api.swagger.json` before changing APIs.
5. Preserve local architecture if it already has factories, repositories, handlers, or generated-code conventions.

## Framework Map

- `config`: env and `.env` loading through `go-envconfig` and `godotenv`.
- `server`: bootstrap manager for gRPC, HTTP gRPC-Gateway, cron, discovery events, and graceful shutdown.
- `server/handler`: embedded Swagger UI handler for generated OpenAPI specs.
- `database`: PostgreSQL GORM connection with `otelgorm`, model registration, and `AutoMigrate`.
- `telemetry`: OpenTelemetry traces, metrics, logs, providers, and slog bridge.
- `logger`: JSON slog logger with Sentry, without the OTel slog bridge.
- `discovery`: service discovery interface and Consul implementation.
- `server/middleware`: CORS middleware used by HTTP gateway.

## Core Rules

- Use a schema-first flow: edit `.proto`, regenerate code, implement generated server interfaces, and register the gRPC-Gateway handler.
- Register gRPC before HTTP because `server.Http` dials the local gRPC server.
- Keep `main.go` mostly wiring: config, telemetry, database, repositories/services, handlers, server registration, `Run`.
- Always call `server.NewServer(logger, tracer, meter)` before `Grpc`, `Http`, `Cron`, or `AddDiscovery`.
- Call `app.Run(ctx)` last; it blocks until cancellation or a server error.
- Use `signal.NotifyContext` for graceful shutdown and call the telemetry shutdown function on exit.
- Register GORM models with `database.AddModel` before `database.Migrate`.
- Use `db.WithContext(ctx)` in repositories so traces propagate into SQL spans.
- Return gRPC errors with `status.Error(codes.Xxx, "...")`; gRPC-Gateway maps these to HTTP responses.
- Treat authentication as application code. The framework only forwards `Authorization` from HTTP to gRPC metadata.

## Reference Files

Read only the files relevant to the task:

- `references/protobuf.md`: protobuf layout, gRPC-Gateway annotations, generation commands, and OpenAPI output.
- `references/server-bootstrap.md`: canonical `main.go`, server lifecycle, and registration order.
- `references/handlers-and-factories.md`: handler structs, RPC methods, gRPC/REST factories, repositories.
- `references/config-and-env.md`: config structs, prefix pitfalls, and environment variables.
- `references/database.md`: PostgreSQL connection, GORM model registration, migrations, repository rules.
- `references/observability.md`: OpenTelemetry setup, logging, tracing, metrics, OTLP env.
- `references/discovery-cron-swagger.md`: Consul discovery, cron tasks, Swagger UI, CORS/headers.
- `references/devops.md`: Taskfile, Docker, generated artifacts, and local development commands.