sharang
80181855bc
PLATFORM_ARCHITECTURE.md §5c schema, end-to-end:
enums: tenant_status (demo/trial/active/frozen/archived),
tenant_kind (customer/demo), idp_kind (oidc/saml),
tenant_project_status (active/archived)
tables: tenants id/slug/name/status/kind/plan/erp_id/
stripe_id/trial_ends_at/contract_dates/
sales_owner
tenant_projects sub-tenancy (GCP-Project style); opt-in via
product manifest.supports_projects=true
tenant_products tenant ↔ product matrix + JSONB config
tenant_idp_config enterprise SSO (OIDC/SAML metadata + verified)
api_keys argon2 hash + prefix + scopes + revoked_at;
single source of truth across all products
audit_log Retraced-compatible: actor/action/target/
product/metadata; indexed for cross-product
filtering (PRODUCT_INTEGRATION_SPEC.md §8.4)
triggers: updated_at auto-bump on every mutable table.
fks: ON DELETE CASCADE for owned rows; SET NULL for audit_log so
forensic history outlives the tenant delete.
cmd/migrate (new binary):
golang-migrate as a library with the migrations embedded via
migrations/embed.go → embed.FS. Sub-commands: up / down / version /
force. Ships as a self-contained binary; in prod it's the Orca init
container per IMPLEMENTATION_PLAN.md §1.7.
Dockerfile builds both binaries; the migrate one is invoked separately
as the init step.
Tests (require Docker; gated by -short):
TestMigrate_upDownRoundTrip schema → 6 tables + 4 enums; down→empty;
up-after-down succeeds (round-trip clean)
TestSeed_canInsertAndQuery insert across every table; FK cascade
works; audit_log SET-NULL keeps the row
TestSlugConstraint tenant.slug regex rejects too-short /
leading dash / trailing dash / uppercase /
underscore
Makefile:
make migrate-up / down / down-all / version / create NAME=...
make test-short → skip integration when Docker isn't around
make build-migrate → just the migrator binary
The handler-layer in-memory store is unchanged; M4.2 swaps it for the
pgx-backed implementation against this schema.
Refs: M4.1
124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
# tenant-registry
|
|
|
|
Multi-tenant glue: orgs, entitlements, API keys, audit.
|
|
|
|
> Part of the **Breakpilot Platform**. For the big picture see [`platform/docs`](https://gitea.meghsakha.com/platform/docs):
|
|
> [Architecture](https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md) ·
|
|
> [Infrastructure](https://gitea.meghsakha.com/platform/docs/src/branch/main/INFRASTRUCTURE.md) ·
|
|
> [Product Integration Spec](https://gitea.meghsakha.com/platform/docs/src/branch/main/PRODUCT_INTEGRATION_SPEC.md) ·
|
|
> [Implementation Plan](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)
|
|
|
|
## What this is
|
|
|
|
Multi-tenant glue: orgs, entitlements, API keys, audit. Scaffolded under milestone M4.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
|
|
|
|
**Plane:** Control
|
|
**Owner:** @sharang
|
|
**Status:** pre-alpha
|
|
**Linked milestone:** [M4.1](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)
|
|
|
|
## Run locally
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```bash
|
|
# 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](https://signoz.meghsakha.com) — 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`](./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`](./LICENSE).
|