ginit

A production-ready Go API boilerplate — auth, teams, and everything wired up so you can start shipping features instead of plumbing.

Built with Go 1.25 + Fiber v2, SQLite by default (swap for Postgres/MySQL when you're ready), and a clean internal/ package layout.

Features

• Authentication — register, login/logout, session cookies, password reset, email change
• Two-factor auth — TOTP setup with QR code (pquerna/otp)
• Teams — auto-created workspace on register, team switching, member invites
• Validation — request validation with go-playground/validator
• Swagger docs — annotated endpoints served at /swagger/ (dev only)
• Extensible drivers — cache, queue, storage, email, and notifications behind small interfaces
• Docker — multi-stage image ready to deploy (AWS Lambda compatible)

Quickstart

cp .env.example .env     # configure your environment
make migrate             # apply database migrations
make build               # compile binaries into ./bin
make run                 # start the API on :3000

Open http://localhost:3000/swagger/ for API docs.

Development with hot reload

air

.air.toml rebuilds and restarts on changes.

Project structure

cmd/
  ginit/          # API server entrypoint
  migrate/        # database migration runner
http/
  controllers/    # request handling (auth, user, team)
  routes/         # route registration
internal/
  auth/           # authentication, sessions, 2FA, middleware
  team/           # teams, memberships, invitations
  session/        # session storage and revocation
  config/         # environment config loading
  bootstrap/      # dependency wiring
  validation/     # request validation helpers
  rbac/           # role-based access control
  notification/   # notifications
  cache/          # cache driver (memory, redis)
  queue/          # queue driver (sync, sqs)
  storage/        # storage driver (local, r2/s3)
  email/          # email driver (log, ses, smtp)
  hook/           # event hooks
  event/          # event types
  http/           # shared HTTP utilities
migrations/       # SQL migrations
docs/             # generated swagger + API reference

Commands

Command	Description
make build	Build binaries into ./bin
make run	Run the API
make migrate	Run database migrations
make create-migration MIGRATION=name	Create a new migration pair
make test	Run tests
make vet / make fmt	Static analysis / formatting
make lint	Run golangci-lint
air	Hot-reload development server
swag init -g cmd/ginit/main.go --parseInternal --parseDependency	Regenerate swagger docs

Configuration

All configuration lives in .env (see .env.example). Key settings:

Variable	Default	Description
APP_ENV	development	Controls swagger exposure (production disables it)
PORT	3000	HTTP listen port
DATABASE_URL	file:./data/domain.db?cache=shared	SQLite connection
SESSION_EXPIRY	720h	Session cookie lifetime

API

Authenticated endpoints use an HTTP-only session_token cookie, set by POST /api/auth/login.

• Auth — /api/auth/* (login, register, forgot/reset password, logout)
• User — /api/user/* (profile, email, password, 2FA)
• Teams — /api/teams/* (list, current, switch, invite, accept)

Detailed reference: docs/ (generated swagger + markdown per module).