vergo

Vergo

Production-ready multi-tenant SaaS backend in Go.

Vergo is a complete SaaS backend that handles the infrastructure every B2B application needs — authentication, organizations, billing, webhooks, storage, and observability — so you can focus on your product's domain logic.

What can you build with Vergo?

Vergo provides the backend foundation for any multi-tenant B2B SaaS. Fork it, add your domain logic, ship:

• Project management tool (like Linear, Asana) — orgs, members, RBAC, and audit are ready
• Developer platform (like Vercel, Railway) — API keys, webhooks, and billing are built-in
• Internal tooling platform — tenant isolation, role-based access, and file storage out of the box
• Collaboration SaaS (like Notion, Figma) — multi-org, invites, and plan gating from day one
• API-first product — full Swagger docs, API key auth, webhook delivery with retries
• Marketplace / Platform — Stripe subscriptions, usage tracking, feature gating per plan

Every feature is production-grade: hashed tokens, HMAC-signed webhooks, structured logs, distributed tracing, fuzz-tested auth. Not a tutorial project.

Architecture

                                    +-------------------+
                                    |   Stripe / S3     |
                                    +--------+----------+
                                             |
Client ──> Gin Router ──> Middleware Chain ──> Handlers ──> Domain Services ──> PostgreSQL
           (rate limit)   (auth, tenant,      (HTTP)       (business logic)    (sqlc queries)
                           RBAC, plan gate)
                                                              |
                                                     Webhook Dispatcher ──> External URLs
                                                     (background, retries)

Design decisions

Features

Quickstart

git clone git@github.com:Ulpio/vergo.git
cd vergo
cp .env.example .env

# Start Postgres + infra
docker compose up -d

# Run API
make run

# Register a user
curl -s localhost:8080/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"demo@example.com","password":"secret123"}' | jq .

# Create an org
TOKEN=$(curl -s localhost:8080/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"demo@example.com","password":"secret123"}' | jq -r .access_token)

curl -s localhost:8080/v1/orgs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Acme Corp"}' | jq .

# Create a project (with org context)
ORG_ID=$(curl -s localhost:8080/v1/context \
  -H "Authorization: Bearer $TOKEN" | jq -r .org_id)

curl -s localhost:8080/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Org-ID: $ORG_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"My First Project","description":"Built with Vergo"}' | jq .

Swagger UI: http://localhost:8080/swagger/index.html

Dev Container

Open in VS Code / Cursor with everything pre-installed:

1. Install Dev Containers extension
2. Ctrl+Shift+P > "Dev Containers: Reopen in Container"

Includes: Go 1.25, PostgreSQL 16, migrate, golangci-lint, swag, air, sqlfluff.

Docker (Production)

docker build -t vergo .
docker run -p 8080:8080 --env-file .env vergo

Pre-built images on every push to main:

docker pull ghcr.io/ulpio/vergo:main

API Reference

Full interactive docs available at /swagger/index.html when running locally.

Public

Authenticated (Bearer JWT or API Key)

Tenant-scoped (requires org context)

Project Structure

cmd/api/                           # Application entrypoint
internal/
  auth/                            # JWT, refresh tokens, password reset
  domain/
    user/                          # Registration, login, password management
    org/                           # Organizations + memberships
    project/                       # Project CRUD
    audit/                         # Immutable audit trail
    apikey/                        # API key lifecycle
    webhook/                       # Endpoints + background dispatcher
    billing/                       # Stripe integration + plan limits
    file/                          # File metadata
    userctx/                       # Active org context
  http/
    handlers/                      # Request/response handling
    middleware/                    # Auth, tenant, RBAC, rate limit, plan gate
    router/                        # Route registration + dependency wiring
  repo/                            # sqlc generated type-safe queries
  pkg/                             # Shared infrastructure (config, db, telemetry, logging)
  storage/s3/                      # S3-compatible storage client
db/
  migrations/                      # 11 SQL migrations
  queries/                         # sqlc query definitions

Configuration

All configuration via environment variables. Copy .env.example to .env and adjust:

Development

make help              # Show all targets
make dev               # Hot-reload with air
make test              # Unit tests
make test-fuzz         # Fuzz tests (JWT + RBAC)
make lint              # golangci-lint
make check             # vet + lint + test (CI equivalent)
make swagger           # Regenerate Swagger docs
make sqlc              # Regenerate sqlc queries
make docker-up         # Start Postgres + infra
make docker-reset      # Reset database (drop volumes)
make migrate-up        # Run pending migrations
make migrate-create NAME=xyz  # Create new migration

Tech Stack

License

MIT