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

Authoritative spec: openapi.yaml. Summary:

Method	Path	Purpose
GET	/healthz	Liveness
GET	/readyz	Pings the store
POST	/v1/tenants	Create a tenant
GET	/v1/tenants/{id}	Read by id
GET	/v1/tenants/by-slug/{slug}	Read by slug (portal middleware uses this)
POST	/v1/tenants/{id}/activate	trial → active
POST	/v1/tenants/{id}/cancel	active → frozen
GET	/v1/entitlements?tenant_id={id}	List product entitlements
GET	/v1/catalog	List requestable products
POST	/v1/catalog/request	Customer requests a product (sales follow-up)
POST	/v1/catalog/trial-request	Self-serve 14-day trial
GET	/v1/api-keys?tenant_id={id}	List keys
POST	/v1/api-keys	Create key (plaintext shown once)
DELETE	/v1/api-keys/{id}	Revoke
POST	/v1/internal/api-keys/verify	Used by headless products to validate inbound keys
POST	/v1/audit	Append an audit event
GET	/v1/audit	Query (cursor-paginated)

State-changing endpoints emit audit events automatically. The OpenAPI contract test (openapi_test.go) asserts every listed path resolves against the committed spec.

Storage

The service picks its store based on DATABASE_URL:

• empty → in-memory store, pre-seeded with the acme tenant (id: 00000000-0000-0000-0000-000000000001). Useful for portal dev without spinning Postgres.
• set → pgx-backed Postgres. Run make migrate-up against the same DSN first.

Both implementations pass the same test harness (internal/server/server_test.go → eachStore).

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.