https://github.com/sandeepkv93/everything-backend-starter-kit
REST API service in Go with Google OAuth login, JWT auth, secure cookie sessions, RBAC authorization, and OpenTelemetry observability.
https://github.com/sandeepkv93/everything-backend-starter-kit
docker-compose go-chi golang grafana k8s kustomize loki mimir oauth2 opentelemetry redis rest-api tempo
Last synced: 3 months ago
JSON representation
REST API service in Go with Google OAuth login, JWT auth, secure cookie sessions, RBAC authorization, and OpenTelemetry observability.
- Host: GitHub
- URL: https://github.com/sandeepkv93/everything-backend-starter-kit
- Owner: sandeepkv93
- License: mit
- Created: 2026-02-07T02:01:07.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-16T03:31:14.000Z (5 months ago)
- Last Synced: 2026-02-16T10:13:41.862Z (5 months ago)
- Topics: docker-compose, go-chi, golang, grafana, k8s, kustomize, loki, mimir, oauth2, opentelemetry, redis, rest-api, tempo
- Language: Go
- Homepage:
- Size: 726 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Everything Backend Starter Kit
[](https://github.com/sandeepkv93/everything-backend-starter-kit/actions/workflows/ci.yml)
[](https://github.com/sandeepkv93/everything-backend-starter-kit/actions/workflows/fuzz-nightly.yml)
[](https://github.com/sandeepkv93/everything-backend-starter-kit/actions/workflows/k8s-kind-smoke.yml)
[](https://go.dev/)
[](https://bazel.build/)
[](LICENSE)
## Table of Contents
- [Overview](#overview)
- [Tech Stack](#tech-stack)
- [Architecture at a Glance](#architecture-at-a-glance)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [License](#license)
## Overview
This repository is a production-oriented Go backend starter that brings together authentication, authorization, observability, and delivery tooling in one baseline:
- Google OAuth login
- Cookie-based JWT session flow (access + refresh)
- Session/device management APIs (`/api/v1/me/sessions`)
- RBAC authorization
- Redis-backed caching for admin list, RBAC permission, and negative lookup flows
- Redis-backed rate limiting and abuse-protection controls
- OpenTelemetry metrics, traces, and logs
- Local tri-signal stack (Grafana + Tempo + Loki + Mimir + OTel Collector)
- Bazel + Gazelle + Task + Wire development workflow
- API server in `cmd/api`
- Operational CLIs in `cmd/migrate`, `cmd/seed`, `cmd/loadgen`, `cmd/obscheck`
- Layered internal packages (`internal/*`) with DI composition through Wire
- Docker Compose local stack for DB + observability
- CI + local hooks enforcing build/test/generation hygiene
## Tech Stack
- Language/runtime: [](https://go.dev/)
- HTTP framework: [](https://github.com/go-chi/chi)
- Persistence: [](https://www.postgresql.org/) [](https://gorm.io/)
- Cache/rate limiting/idempotency backend: [](https://redis.io/)
- Object storage: [](https://min.io/)
- Auth: [](https://developers.google.com/identity/protocols/oauth2) [](https://jwt.io/)
- Observability: [](https://opentelemetry.io/) [](https://opentelemetry.io/docs/collector/) [](https://grafana.com/) [](https://grafana.com/oss/tempo/) [](https://grafana.com/oss/loki/) [](https://grafana.com/oss/mimir/)
- Tooling: [](https://taskfile.dev/) [](https://github.com/bazelbuild/bazelisk) [](https://github.com/bazelbuild/bazel-gazelle) [](https://github.com/google/wire) [](https://golangci-lint.run/) [](https://github.com/securego/gosec) [](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck) [](https://github.com/gitleaks/gitleaks)
## Architecture at a Glance
- Request path: `internal/http` ==> `internal/service` ==> `internal/repository` ==> `internal/database`
- Cross-cutting concerns: `internal/security`, `internal/observability`, middleware, and Redis-backed controls
- Dependency injection: `internal/di` (Wire-generated injectors validated in CI)
```mermaid
flowchart LR
User[Web or API Client] --> Router[Chi Router + Middleware]
Router --> Handlers[HTTP Handlers]
Handlers --> Services[Service Layer]
Services --> Repos[Repository Layer]
Repos --> DB[(PostgreSQL)]
Services --> Redis[(Redis)]
Services --> MinIO[(MinIO/S3)]
Handlers --> OAuth[Google OAuth Provider]
OAuth --> Handlers
Router -. request logs, metrics, traces .-> OTelSDK[OTel SDK]
Services -. cache and auth metrics .-> OTelSDK
Repos -. db telemetry .-> OTelSDK
OTelSDK --> Collector[OTel Collector]
Collector --> Tempo[Tempo Traces]
Collector --> Loki[Loki Logs]
Collector --> Mimir[Mimir Metrics]
Grafana[Grafana] --> Tempo
Grafana --> Loki
Grafana --> Mimir
Loadgen[cmd/loadgen] --> Router
Obscheck[cmd/obscheck] --> Grafana
```
## Quick Start
### Prerequisites:
- [Go `1.26.0`](https://go.dev/dl/)
- [Task](https://taskfile.dev/)
- [Bazelisk](https://github.com/bazelbuild/bazelisk) (uses Bazel `9.0.0` from `.bazelversion`)
- [Docker](https://docs.docker.com/get-docker/) + [Docker Compose](https://docs.docker.com/compose/)
### Clone the repo and cd into it
```bash
git clone git@github.com:sandeepkv93/everything-backend-starter-kit.git
cd everything-backend-starter-kit
```
### Configure environment
```bash
cp .env.example .env
```
### Start local dependencies and run API
```bash
task docker-up
task migrate
task seed
task run
```
### Database reset/backup/restore (local)
These commands operate on the Docker Compose-managed Postgres service (`db`) and its data volume.
```bash
# reset Postgres container + DB volume and start fresh db service
task integration:reset-db
# create SQL backup (default: backups/backup_.sql)
task integration:backup-db
# restore from backup file
task integration:restore-db FILE=backups/backup_20260217_103000.sql
```
### Expected success checks
```bash
curl -sSf http://localhost:8080/health/live
curl -sSf http://localhost:8080/health/ready
```
### REST Client Collection (Manual API Verification)
Use the checked-in VS Code REST Client collections to exercise all APIs (including detailed RBAC/admin flows) end-to-end.
1. Install the REST Client extension: `https://marketplace.visualstudio.com/items?itemName=humao.rest-client`
2. Open the detailed split collections in `api/rest-client/` (recommended):
- `00-quickstart.rest`
- `01-auth.rest`
- `02-user-me-sessions-avatar.rest`
- `03-products.rest`
- `04-feature-flags.rest`
- `05-admin-rbac.rest`
3. Optionally use `api/everything-backend-starter-kit.rest` as a monolithic fallback
4. Update variables at the top (`@baseUrl`, user credentials, IDs) for your local environment
5. Run requests in sequence:
- health checks
- local login/register
- CSRF-protected endpoints (`/auth/refresh`, `/auth/logout`, `/auth/local/change-password`, `/me/*` mutating routes)
- admin RBAC endpoints with a user that has required permissions
Notes:
- Cookie-based auth is used, so enable REST Client cookie persistence (`rest-client.rememberCookiesForSubsequentRequests`).
- Idempotency-key headers are included for routes that can be wrapped by idempotency middleware.
- When routes change in `internal/http/router/router.go`, update `api/rest-client/*.rest` (and monolithic file if used) in the same PR.
### Pre-commit workflow
Install hooks and local tooling:
```bash
task hooks-install
```
Run the full hook suite manually:
```bash
task hooks-run-all
# or, if pre-commit is already on PATH:
pre-commit run --all-files
```
Hook coverage includes Go formatting/linting (`gofmt`, `goimports`, `golangci-lint`, `go mod tidy`), Dockerfile linting (`hadolint`), YAML linting (`yamllint`), and secret scanning (`detect-secrets`).
### Mock Generation
Deterministic gomock files are generated from exported interfaces in key packages.
```bash
task mockgen:install
task mockgen
task mockgen-check
```
Generated output directories:
- `internal/repository/gomock`
- `internal/service/gomock`
- `internal/health/gomock`
- `internal/http/middleware/gomock`
CI enforces drift checks by re-running the generator.
### Feature flags
Runtime feature toggles support user evaluation and RBAC-gated admin management.
- User evaluation endpoints:
- `GET /api/v1/feature-flags`
- `GET /api/v1/feature-flags/{key}`
- Admin endpoints (require `feature_flags:read` / `feature_flags:write`):
- `GET|POST /api/v1/admin/feature-flags`
- `GET|PATCH|DELETE /api/v1/admin/feature-flags/{id}`
- `GET|POST /api/v1/admin/feature-flags/{id}/rules`
- `PATCH|DELETE /api/v1/admin/feature-flags/{id}/rules/{rule_id}`
Rule matching precedence during evaluation:
`user` > `role` > `org` > `environment` > `percent` > flag default.
### Products Blueprint Module
Sample `products` CRUD module demonstrates domain/repository/service/handler layering with RBAC-protected routes and paginated list responses.
- Endpoints:
- `GET /api/v1/products` (requires `products:read`)
- `GET /api/v1/products/{id}` (requires `products:read`)
- `POST /api/v1/products` (requires `products:write`)
- `PUT /api/v1/products/{id}` (requires `products:write`)
- `DELETE /api/v1/products/{id}` (requires `products:delete`)
- Pagination defaults:
- `page=1`, `page_size=20`, max `page_size=100`
Endpoints:
- API base URL: `http://localhost:8080`
- Grafana UI: `http://localhost:3000` (`admin` / `admin`)
- MinIO Console: `http://localhost:9001` (`minioadmin` / `minioadmin`)
## Documentation
- [Project guide (full documentation)](docs/project-guide.md)
- [Architecture and flow diagrams](docs/diagrams.md)
- [Kubernetes deployment guide](k8s/README.md)
- [Audit Taxonomy](docs/audit-taxonomy.md)
## License
MIT. See [LICENSE](LICENSE) for details.