Service Discovery for Tenant-Manager

Detect service identity (run in parallel):

1. Service name:
   - Grep tool: pattern "const ApplicationName" in internal/bootstrap/ cmd/ --include="*.go"
   - Extract the string value (e.g., "ledger", "plugin-crm", "onboarding")

2. Service type:
   - Read go.mod first line (module path)
   - If module path contains "plugin-" → serviceType = "plugin"
   - Else → serviceType = "product"

3. Project structure:
   - Glob tool: pattern "components/*/cmd/app/main.go"
   - If multiple matches → unified service with multiple components (like ledger)
   - If no matches → Glob: "cmd/app/main.go" or "cmd/*/main.go" → single-component service

4. Unified service detection (if multiple components found):
   - Glob tool: pattern "components/*/internal/bootstrap/config.go"
   - For each component, grep "const ApplicationName" → collect module names
   - Check if a "parent" component imports and composes the others
     (grep "InitServiceWithOptions\|InitServersWithOptions" in each component's bootstrap)
   - The parent component's ApplicationName = service name
   - Each child component's ApplicationName = module name

Store results:
  service_name = "{detected name}"
  service_type = "product" | "plugin"
  is_unified = true | false
  components = [{name, path, applicationName}]  // if unified

Phase 2: Module Detection

Detect modules (run in parallel):

Strategy A — Explicit WithModule calls (preferred):
   - Grep tool: pattern "WithModule\(" in internal/ components/ --include="*.go"
   - Extract module names from the string argument: WithModule("onboarding") → "onboarding"
   - Deduplicate (same module name used in tmpostgres, tmmongo, tmrabbitmq = one module)

Strategy B — Component-based (if no WithModule found):
   - Each component with its own internal/bootstrap/ and ApplicationName = one module
   - module_name = ApplicationName of that component

Strategy C — Single-component service (no components/ directory):
   - module_name = service ApplicationName
   - This service has exactly 1 module

Merge strategies (A takes precedence, B fills gaps, C is fallback):
  modules = [
    {name: "onboarding", component_path: "components/onboarding/"},
    {name: "transaction", component_path: "components/transaction/"},
  ]
  // or for single-component:
  modules = [
    {name: "my-service", component_path: "./"}
  ]

Phase 3: Resource Detection per Module

For EACH detected module, scan its adapter directory:

base_path = module.component_path + "internal/adapters/"
// For single-component: base_path = "internal/adapters/"

Detect resources (run in parallel per module):

1. PostgreSQL:
   - Glob tool: pattern "{base_path}postgres/*" (directories)
   - If any subdirectory exists → resource "postgresql" detected
   - Count subdirectories = repository count
   - List subdirectory names = repository names (e.g., "organization", "ledger", "account")

2. MongoDB:
   - Glob tool: pattern "{base_path}mongodb/*" OR "{base_path}mongo/*" (directories)
   - If any subdirectory or file exists → resource "mongodb" detected
   - Note: metadata repositories use collection-per-entity pattern

3. RabbitMQ:
   - Glob tool: pattern "{base_path}rabbitmq/*" (files)
   - If any file exists → resource "rabbitmq" detected
   - Grep: "producer\|Producer" in matched files → has producer
   - Grep: "consumer\|Consumer" in matched files → has consumer
   - Grep: "QUEUE\|queue" in the module's bootstrap config → extract queue names

4. Redis (informational only — NOT a tenant-manager resource):
   - Glob tool: pattern "{base_path}redis/*" (files)
   - If exists → note "Redis detected — managed via key prefixing, no tenant-manager registration needed"

Store per module:
  module.resources = [
    {type: "postgresql", repos: ["organization", "ledger", ...], count: 7},
    {type: "mongodb", collections_info: "metadata (collection-per-entity)"},
    {type: "rabbitmq", has_producer: true, has_consumer: true, queues: ["BTO"]},
  ]
  module.redis_detected = true | false  // informational only

Phase 3.5: Database Name Detection per Module

For EACH detected module, extract the actual database names from configuration:

config_path = module.component_path + "internal/bootstrap/config.go"
env_path    = module.component_path + ".env.example"
// For single-component: config_path = "internal/bootstrap/config.go", env_path = ".env.example"

DETECT database names (run in parallel per module):

1. Bootstrap config struct (source of truth for env var names):
   - Read config_path
   - Grep for env tags matching database name patterns:
     a. PostgreSQL: env:"DB_NAME" or env:"DB_<MODULE_UPPER>_NAME"
     b. MongoDB:    env:"MONGO_NAME" or env:"MONGO_<MODULE_UPPER>_NAME"
   - Extract the Go struct field name and env var name
   - Note: Prefixed variants (DB_<MODULE>_NAME) are used in unified services
     where a parent component composes child modules (e.g., ledger composing
     onboarding + transaction). Non-prefixed (DB_NAME) is the standard form.

2. .env.example (source of truth for default values):
   - Read env_path
   - For each env var name found in step 1, extract the default value:
     a. PostgreSQL: DB_NAME=<value> or DB_<MODULE_UPPER>_NAME=<value>
     b. MongoDB:    MONGO_NAME=<value> or MONGO_<MODULE_UPPER>_NAME=<value>
   - These are the actual database names used in development

3. External datasources (DATASOURCE_* pattern):
   - Grep in env_path for: DATASOURCE_*_DATABASE=<value>
   - Each match = one external database connection
   - Extract: datasource name (from env var), database name (from value), type (from DATASOURCE_*_TYPE)
   - These represent read-only connections to OTHER services' databases

4. Fallback (if .env.example not found or value empty):
   - Use the module name as likely database name (common convention)
   - Flag as "inferred — verify manually"

Store per module:
  module.databases = {
    postgresql: {env_var: "DB_NAME", default_value: "onboarding", source: ".env.example"},
    mongodb:    {env_var: "MONGO_NAME", default_value: "onboarding", source: ".env.example"},
  }
  module.external_datasources = [
    {name: "onboarding", env_prefix: "DATASOURCE_ONBOARDING", database: "onboarding", type: "postgresql"},
  ]

Phase 3.6: Shared Database Detection (Cross-Module Analysis)

AFTER all modules have been scanned (Phases 3 + 3.5 complete), cross-reference
database names across ALL modules to detect shared databases.

This is CRITICAL for tenant-manager: when two modules point to the same database,
tenant-manager must provision ONE database (not two) and grant access to both modules.

DETECT shared databases:

1. Internal databases (same DB name across modules):
   - Group all module.databases entries by (resource_type, default_value)
   - If 2+ modules share the same (type, db_name) → mark as SHARED
   - Example: module-a.mongodb.default_value == module-b.mongodb.default_value == "myservice-db"
     → shared_databases.mongodb["myservice-db"] = ["module-a", "module-b"]
   - Example: module-a.postgresql.default_value == module-b.postgresql.default_value == "myservice"
     → shared_databases.postgresql["myservice"] = ["module-a", "module-b"]

2. External datasources (same DATASOURCE_*_DATABASE across modules):
   - Group all module.external_datasources by (database, type)
   - If 2+ modules reference the same external DB → mark as SHARED
   - Example: module-a and module-b both have DATASOURCE_FOO_DATABASE=foo
     → shared_external["foo"] = ["module-a", "module-b"]

TENANT-MANAGER IMPLICATIONS (include in report):

For shared MongoDB:
  - Tenant-manager provisions ONE MongoDB database per tenant
  - Both modules receive their own credentials to the SAME tenant database
  - Collections are shared — both modules read/write the same collections

For shared PostgreSQL:
  - Tenant-manager provisions ONE PostgreSQL database per tenant
  - Both modules connect to the SAME database
  - Each module may use the same schema or have its own schema within the
    shared database (depends on service design — check DATASOURCE_*_SCHEMAS)
  - Tenant-manager creates the schema(s) with tables inside the single database
  - Each module gets its own credentials with appropriate schema access

The registration checklist must list the database ONCE with all modules
that access it. DO NOT create duplicate databases.

Store results:
  shared_databases = {
    mongodb: {
      "myservice-db": {modules: ["module-a", "module-b"], provision_once: true}
    },
    postgresql: {
      // empty if no shared PG databases detected in this example
    }
  }
  shared_external = {
    "foo": {modules: ["module-a", "module-b"], type: "postgresql"}
  }

Phase 3.7: MongoDB Index Detection & Script Generation

Only execute this phase if MongoDB was detected in any module during Phase 3.

Read the full reference: references/mongodb-index-detection.md (in this skill's directory)

Summary of steps:

1. Detect in-code indexes — scan EnsureIndexes() / IndexModel{} in MongoDB adapter files
2. Detect existing scripts — scan scripts/mongodb/*.js for createIndex calls
3. Cross-reference — match in-code indexes against script indexes (covered / missing_script / script_only)
4. Generate missing scripts — create mongosh-compatible .js scripts following the idempotent createIndexSafely pattern (see reference for full template)
5. Upload to S3 — asks which bucket to use, then uploads scripts following the migrations bucket convention: s3://{bucket}/{service}/{module}/mongodb/ (requires valid AWS credentials; verify with aws sts get-caller-identity). S3 upload failures are non-blocking — skill continues to Phase 4 with upload status reported in the HTML report

Store results for Phase 4 report:

  index_coverage = {
    covered: [{collection, keys, in_code_file, script_file}],
    missing_script: [{collection, keys, in_code_file}],
    script_only: [{collection, keys, script_file}],
  }

Phase 4: Generate Visual Report

MANDATORY: Invoke Skill("ring:visual-explainer") to produce the report.

Read default/skills/visual-explainer/templates/data-table.html first to absorb table patterns.

The report is focused on what needs to be configured in the tenant-manager for multi-tenant to work for this service.

The HTML report MUST include these sections:

1. Tenant-Manager Configuration Summary

Card showing:

• Service Name: {service_name}
• Service Type: product | plugin
• Modules: {count}
• Total Resources: {count across all modules}
• Shared Databases: {count} (databases accessed by 2+ modules — provision once)
• External Datasources: {count} (read-only connections to other services)

## Tenant-Manager Configuration for: {service_name}

One card per module. When a resource is shared with another module, display a
**SHARED** badge and list the other modules that access it.

**Example A — Shared database (two modules pointing to the same DB):**

┌─────────────────────────────────────────────────┐ │ MODULE: module-a │ ├─────────────────────────────────────────────────┤ │ MongoDB ✅ │ │ DB name: "myservice-db" (MONGO_NAME) │ │ 🔗 SHARED DB with: module-b │ │ ⚠ Provision ONCE — both modules get │ │ credentials to the same tenant database │ │ │ │ RabbitMQ ✅ (producer) │ └─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐ │ MODULE: module-b │ ├─────────────────────────────────────────────────┤ │ MongoDB ✅ │ │ DB name: "myservice-db" (MONGO_NAME) │ │ 🔗 SHARED DB with: module-a │ │ ⚠ Provision ONCE — see module-a │ │ │ │ RabbitMQ ✅ (consumer) │ └─────────────────────────────────────────────────┘

**Example B — Separate databases (ledger-style: each module has its own DB):**

┌──────────────────────────────────────────┐ │ MODULE: onboarding │ ├──────────────────────────────────────────┤ │ PostgreSQL ✅ (7 repositories) │ │ DB name: "onboarding" (DB_NAME) │ │ organization, ledger, account, │ │ asset, portfolio, segment, │ │ accounttype │ │ │ │ MongoDB ✅ (metadata) │ │ DB name: "onboarding" (MONGO_NAME) │ └──────────────────────────────────────────┘

**Database name display rules:**
- Show the default value from `.env.example` in quotes
- Show the env var name in parentheses for reference
- If inferred (no `.env.example`), show with "(inferred)" suffix
- External datasources appear in a separate sub-section per module
- **SHARED databases** get a `🔗 SHARED DB with: <modules>` line and a `⚠ Provision ONCE` warning

### 2. MongoDB Index Scripts

Table showing what scripts exist and where they are:

If there are indexes in code without scripts:

⚠️ {N} indexes detected in code without corresponding scripts. Scripts were generated in scripts/mongodb/ — upload to S3 at s3://{bucket}/{service}/{module}/mongodb/ to make them available for dedicated tenant database provisioning.

### 2.5. Shared Databases Summary

**Only display this section if shared databases were detected in Phase 3.6.**

Table format:

**Provision strategy explanations:**
- **1 database, N credential sets** — tenant-manager creates ONE database per tenant; each module gets its own credentials to the same DB. For MongoDB: shared collections. For PostgreSQL: shared schema or separate schemas within the same database.
- **1 database, separate schemas** — when 2 modules share a PostgreSQL DB but use different schemas, tenant-manager creates ONE database with all schemas inside; each module accesses its own schema with its own credentials
- **Read-only, shared credentials** — external datasource (not tenant-managed); modules connect with the same read-only credentials

### 3. Service Hierarchy Diagram

Mermaid diagram. Shared databases use a single node with connections from multiple modules:

**Example A — Shared database (two modules, same DB):**

```mermaid
graph TD
    S["Service: myservice (product)"]
    S --> M1["Module: module-a"]
    S --> M2["Module: module-b"]
    DB1[("MongoDB\nDB: myservice-db\n🔗 SHARED")]
    M1 --> DB1
    M2 --> DB1
    M1 --> Q1["RabbitMQ"]
    M2 --> Q2["RabbitMQ"]

Example B — Separate databases (ledger-style):

graph TD
    S["Service: ledger (product)"]
    S --> M1["Module: onboarding"]
    S --> M2["Module: transaction"]
    M1 --> R1["PostgreSQL (7 repos)\nDB: onboarding"]
    M1 --> R2["MongoDB\nDB: onboarding"]
    M2 --> R3["PostgreSQL (6 repos)\nDB: transaction"]
    M2 --> R4["MongoDB\nDB: transaction"]
    M2 --> R5["RabbitMQ"]

Diagram rules:

• Shared databases use a SINGLE cylindrical node connected to ALL modules that access it
• Shared nodes include 🔗 SHARED label
• Non-shared databases are drawn per module as before
• RabbitMQ is always drawn per module (no shared analysis needed for queues)

4. Tenant-Manager Registration Checklist

Example A — With shared databases (two modules, same DB):

## What to register in tenant-manager:

- [ ] **Service:** `myservice` (type: product, isolation: database)

- [ ] **Module:** `module-a`
  - [ ] Resource: mongodb (DB: "myservice-db", env: MONGO_NAME)
        ⚠ SHARED DB with module-b — provision ONCE, grant access to both
  - [ ] Resource: rabbitmq

- [ ] **Module:** `module-b`
  - [ ] Resource: mongodb → SAME DB as module-a ("myservice-db")
        DO NOT create a second database — reuse module-a's
  - [ ] Resource: rabbitmq

## Shared databases (provision ONCE, access by multiple modules):
| DB Type  | Database Name   | Modules              | Action                        |
|----------|-----------------|----------------------|-------------------------------|
| mongodb  | "myservice-db"  | module-a, module-b   | 1 database, 2 credential sets |

Example B — Without shared databases (ledger-style):

## What to register in tenant-manager:

- [ ] **Service:** `ledger` (type: product, isolation: database)

- [ ] **Module:** `onboarding`
  - [ ] Resource: postgresql (DB: "onboarding", env: DB_NAME)
  - [ ] Resource: mongodb (DB: "onboarding", env: MONGO_NAME)

- [ ] **Module:** `transaction`
  - [ ] Resource: postgresql (DB: "transaction", env: DB_NAME)
  - [ ] Resource: mongodb (DB: "transaction", env: MONGO_NAME)
  - [ ] Resource: rabbitmq

Checklist rules:

• Shared databases appear with ⚠ SHARED DB warning on FIRST module and → SAME DB as <module> reference on subsequent modules
• A dedicated "Shared databases" summary table lists all shared DBs with provisioning action
• External datasources note which modules access them
• MongoDB index S3 paths are listed per module when available

Save to: docs/service-discovery.html in the project root.

Open in browser:

macOS: open docs/service-discovery.html
Linux: xdg-open docs/service-discovery.html

Anti-Rationalization Table

Pressure Resistance