ring:adding-multi-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:

Alias	Import Path	Purpose
client	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/client	Tenant Manager HTTP client
tmcore	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/core	Context helpers, resolvers
tmmiddleware	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/middleware	TenantMiddleware (WithPG/WithMB)
tmpostgres	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/postgres	PostgresManager
tmmongo	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/mongo	MongoManager
tmrabbitmq	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/rabbitmq	RabbitMQ Manager
valkey	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/valkey	Redis key prefixing
s3	github.com/LerianStudio/lib-commons/v5/commons/dispatch layer/s3	S3 key prefixing
secretsmanager	github.com/LerianStudio/lib-commons/v5/commons/secretsmanager	M2M credentials

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

Gate	Name	Condition	Agent
0	Stack Detection + Compliance Audit	Always	Orchestrator
1	Codebase Analysis (multi-tenant focus)	Always	ring:codebase-explorer
1.5	Implementation Preview	Always	ring:visualizing
2	lib-commons v5 + lib-auth v2 Upgrade	Skip only if both already pinned in go.mod	ring:backend-go
3	Multi-Tenant Configuration	Always	ring:backend-go
4	Tenant Middleware (TenantMiddleware with WithPG/WithMB)	Always	ring:backend-go
5	Repository Adaptation	Always per detected DB	ring:backend-go
5.5	M2M Secret Manager	Skip if service has no targetServices	ring:backend-go
6	RabbitMQ Multi-Tenant	Skip if no RabbitMQ	ring:backend-go
7	Metrics & Backward Compat	Always	ring:backend-go
8	Tests	Always	ring:backend-go
9	Code Review	Always	9 defaults + triggered specialists in parallel
10	User Validation	Always	User
11	Activation Guide	Always	Orchestrator

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

Severity	Criteria
CRITICAL	Cross-tenant data leak; wrong tenant identifier (organization_id)
HIGH	Missing TenantMiddleware; wrong env var names; no circuit breaker
MEDIUM	Missing circuit breaker; incomplete metrics
LOW	Missing env var comments; pool tuning notes