tenant-registry/README.md

tenant-registry

Multi-tenant glue: orgs, entitlements, API keys, audit.

Part of the Breakpilot Platform. For the big picture see platform/docs: Architecture · Infrastructure · Product Integration Spec · Implementation Plan

What this is

Multi-tenant glue: orgs, entitlements, API keys, audit. Scaffolded under milestone M4.1. See platform/docs for the full architecture context.

Plane: Control Owner: @sharang Status: pre-alpha Linked milestone: M4.1

Run locally

# Prerequisites: Go 1.25+
# Dependencies (Keycloak, pg-app) come from the dev stack — see platform/orca-platform/dev.

# In one terminal — bring up dev dependencies (in the orca-platform clone):
cd /path/to/platform/orca-platform && make dev-up

# In another — run the service:
make dev          # APP_ENV=dev, listens on :8090 (Keycloak owns :8080 in the dev stack)
make test         # unit tests
make build        # compile to ./bin/tenant-registry

Env vars (override at the shell):

Var	Default	Purpose
APP_ENV	dev	one of dev, stage, prod
ADDR	:8090	listen address (avoids Keycloak's :8080)
KEYCLOAK_ISSUER	http://localhost:8080/realms/breakpilot-dev	OIDC issuer URL
DATABASE_URL	empty (in-memory store in skeleton)	Postgres DSN, wired up in the M4.1 schema PR

Endpoints

Method	Path	Returns
GET	/healthz	{"status":"ok"} — liveness probe
GET	/v1/tenants/by-slug/{slug}	200 with tenant JSON, 404 if missing
GET	/v1/tenants/{id}	200 with tenant JSON, 404 if missing

The skeleton's store is in-memory and pre-seeded with one tenant:

{
  "id": "00000000-0000-0000-0000-000000000001",
  "slug": "acme",
  "name": "Acme Inc.",
  "status": "active",
  "plan": "professional",
  "products": ["certifai", "compliance"]
}

So curl http://localhost:8090/v1/tenants/by-slug/acme works the moment make dev is up.

The full schema (6 tables: tenants, tenant_projects, tenant_products, tenant_idp_config, api_keys, audit_log — per PLATFORM_ARCHITECTURE.md §5c) lives at migrations/0001_init.up.sql. The handler-layer in-memory store is still wired in by default; the pgx-backed store + the full REST surface lands in M4.2.

Schema migrations (M4.1)

# Apply all pending migrations against the dev Postgres (assumes
# `make dev-up` in platform/orca-platform is running):
make migrate-up

# Inspect current version:
make migrate-version

# Roll back the most recent migration:
make migrate-down

# Wipe everything (DESTRUCTIVE — only safe against a dev DB):
make migrate-down-all

# Create the next pair of empty migration files:
make migrate-create NAME=add_team_table

Migrations are embedded into both cmd/server and cmd/migrate via migrations/embed.go. In production, cmd/migrate ships as an Orca init container so the schema is applied before the API server starts (IMPLEMENTATION_PLAN.md §1.7: migrations are forward-only and run as an init container before the service).

The migrations package ships three integration tests (require Docker):

Test	What it asserts
TestMigrate_upDownRoundTrip	up → all 6 tables + 4 enums exist; down → schema empty; up again succeeds
TestSeed_canInsertAndQuery	end-to-end insert across all 6 tables, FK cascade behaviour, audit_log SET-NULL on tenant delete
TestSlugConstraint	tenant slug regex enforced (rejects too-short / leading dash / uppercase / underscore)

Run them with make test. Use make test-short in environments without Docker.

Deployment

Env	URL	How
dev	http://localhost:8090	make dev
stage	https://tenant-registry.stage.breakpilot.com	auto on merge to main
prod	https://tenant-registry.breakpilot.com	manual: tag vX.Y.Z + sign-off

Rollback: orca rollout undo tenant-registry --env={{env}}.

Observability

• Traces, logs, metrics: SigNoz — service name tenant-registry
• Audit events: Tenant Registry /audit (Retraced-shape schema)
• On-call: oncall@breakpilot.com · runbook at platform/docs/runbooks/tenant-registry.md

Contributing

See CONTRIBUTING.md. TL;DR: branch from main, open a PR, 1 review + green CI, squash-merge.

License

Proprietary — all rights reserved. Copyright (c) 2026 Sharang Parnerkar and Benjamin Boenisch. See LICENSE.