ring-adding-multi-tenancy

name: ring:adding-multi-tenancy description: "Adding database-per-tenant isolation into a Go service end-to-end via an 11-gate cycle: detects the stack, audits compliance, then dispatches backend agents to implement tenantId-from-JWT routing through the lib-commons v5 dispatch layer (config, middleware, repositories, metrics, tests) and runs reviewers. Use when adding tenant isolation to a Go service. Skip for non-Go services or organization_id-style soft tenancy."

Multi-Tenant Development Cycle

When to use

• User requests multi-tenant implementation for a Go service
• User asks to add tenant isolation to an existing service
• Task mentions "multi-tenant", "tenant isolation", "dispatch layer", "postgres.Manager", "WithPG", "WithMB", "EventListener", "TenantCache", "TenantLoader"

Skip when

• Service is not a Go project
• Task does not involve multi-tenancy or tenant isolation
• Service is a shared infrastructure component operating outside tenant context
• Task is documentation-only or non-code

You orchestrate. Agents implement. NEVER use Edit/Write/Bash on Go source files. All code changes go through Task(subagent_type="ring:backend-go"). TDD mandatory for all implementation gates (RED → GREEN → REFACTOR).

Multi-Tenant Architecture

Isolation: tenantId from JWT → dispatch layer middleware → database-per-tenant. organization_id is NOT multi-tenant. tenantId from JWT is the ONLY mechanism.

Standards reference: https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/multi-tenant.md

Sub-package import reference:

Key mandatory requirements:

• MULTI_TENANT_URL — correct env var name (NOT TENANT_MANAGER_ADDRESS)
• 4 canonical metrics (from multi-tenant.md) — all MANDATORY
• Circuit breaker: client.WithCircuitBreaker — MANDATORY
• Service API key: client.WithServiceAPIKey — MANDATORY
• Tenant middleware: per-route WhenEnabled() — NOT global app.Use
• All context helpers: tmcore.GetPGContext(ctx) / tmcore.GetMBContext(ctx) — NEVER .GetDB() directly

Mandatory agent instruction (include in EVERY dispatch):

WebFetch https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/multi-tenant.md. Use exact import paths from skill. Do NOT invent sub-package paths. TDD: RED → GREEN → REFACTOR for every gate.

Gate Overview

Gates execute sequentially. Existing multi-tenant code ≠ compliance. Gate 0 audit is mandatory.

Gate 0: Stack Detection + Compliance Audit

Orchestrator executes directly. Two phases:

Phase 1: Stack Detection

grep "lib-commons" go.mod
grep "lib-auth" go.mod
grep -rn "postgresql\|pgx" internal/ go.mod
grep -rn "mongodb\|mongo" internal/ go.mod
grep -rn "redis\|valkey" internal/ go.mod
grep -rn "rabbitmq\|amqp" internal/ go.mod
grep -rn "s3\|ObjectStorage" internal/
grep -rn "MULTI_TENANT_ENABLED\|dispatch layer" internal/
grep -rn "client_credentials\|M2M\|secretsmanager" internal/

Phase 2: Compliance Audit (if multi-tenant code detected)

Run A1-A8 checks (grep-based):

• A1: MULTI_TENANT_URL used (not TENANT_MANAGER_ADDRESS or variants)
• A2: WithCircuitBreaker on TM client
• A3: WithServiceAPIKey on TM client
• A4: tmcore.GetPGContext / tmcore.GetMBContext used (not .GetDB() / .GetDatabase())
• A5: Tenant middleware per-route WhenEnabled() (not global app.Use)
• A6: Redis keys use valkey.GetKeyContext
• A7: S3 keys use s3.GetS3KeyStorageContext
• A8: No global DB singletons (var db *sql.DB or var client *mongo.Client)

Any NON-COMPLIANT → corresponding gate MUST execute.

Severity Reference