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