backend-go

name	backend-go
description	Go gRPC backend patterns for a multi-tenant SaaS platform. Supports MongoDB and PostgreSQL — detect which database the user mentions and apply the matching patterns from database-patterns.md. Default to MongoDB if unspecified.

Backend Go Skill

Comprehensive guide for working with a Go gRPC backend — a multi-tenant SaaS platform using the Repository-Service pattern with modular business domains, shared utility packages, and a gRPC-Gateway HTTP bridge.

Tech Stack

Layer	Technology	Version
Language	Go	1.22+
Transport	gRPC + gRPC-Gateway	grpc v1.71, gateway v2.26
Database	MongoDB	Driver v1.17
Database (alt)	PostgreSQL	pgx v5 / sqlx
Proto	Protocol Buffers v3	Buf CLI v2
Auth	JWT (golang-jwt v5)	Access + Refresh
Metrics	Prometheus	client_golang v1.20
WebSocket	Gorilla WebSocket	v1.5
OTP	TOTP (pquerna/otp)	Google Authenticator
Email	Resend	v2.13
IDs	ULID (oklog/ulid v2)	Sortable, unique
OAuth	Goth	Google provider
Hot Reload	Air	.air.toml

Quick Reference

Topic	File
Folder structure	folder-structure.md
Module anatomy	module-anatomy.md
Infrastructure utils	infrastructure.md
Interceptor chain	interceptors.md
Database patterns	database-patterns.md
Proto & Buf	proto-and-buf.md
Makefile & dev tooling	makefile-and-tooling.md
Adding a new module	new-module-checklist.md

Module Summary

Modules vary per project. Each module follows the same 3-file layout with an InitIndexes + NewRepository + NewService pattern. Common core modules include:

Module	Responsibility
auth	User accounts, JWT, 2FA, OAuth, sessions, trusted devices
company	Multi-tenant organization/branch/member management
billing	Payment processing, webhooks, subscription billing
role	RBAC role/permission management
subscription	Plan lifecycle, branch-scoped subscriptions
notification	In-app notification delivery
health	Health/readiness/liveness probes
activity	Audit activity logging

Entrypoints

File	Purpose
cmd/main.go	Server bootstrap — config, DB, utilities, gRPC server, HTTP gateway, cron, shutdown
cmd/register.go	Module dependency wiring — creates repos, services, registers gRPC servers
cmd/gateway.go	HTTP gateway — gRPC-Gateway mux, CORS, OAuth routes, WebSocket, health endpoints
cmd/seed/main.go	Database seeder (standalone)

Ports

Port	Protocol	Purpose
8080	HTTP	gRPC-Gateway REST API
50050	gRPC	Native gRPC
9090	HTTP	Prometheus metrics

Key Patterns

1. Repository-Service — Every module follows <module>.go (types) → <module>_repo.go (data access) → <module>_service.go (business logic + gRPC handlers)
2. Constructor injection — All dependencies passed explicitly, nil-safe
3. gRPC-first — Proto is source of truth; HTTP is auto-generated via gateway
4. Interceptor chain — 8 unary + 5 stream interceptors for cross-cutting concerns
5. Graceful shutdown — ShutdownCoordinator manages ordered teardown of components
6. Versioned migrations — MigrationRunner (MongoDB) or golang-migrate (PostgreSQL) with sequential version numbers
7. Event-driven side effects — EventBus for decoupled reactions to user actions
8. Feature flags — DB-backed with 30s in-memory refresh
9. Generic pagination — database.Paginate[T]() for typed paginated queries
10. DB-agnostic repositories — The Repository interface is the same regardless of whether the backing store is MongoDB or PostgreSQL; only the implementation changes