/mapping-service-resources

name: ring:mapping-service-resources
description: "Mapping a Go service's Service -> Module -> Resource hierarchy for dispatch-layer registration: detects modules and per-module PostgreSQL/MongoDB/RabbitMQ resources, database names, and shared databases, generates MongoDB index migration pairs (.up.json/.down.json), detects existing Postgres migrations, emits an HTML report, and offers opt-in S3 upload. Use before ring:adding-multi-tenancy on a new service. Skip for non-Go projects."

Service Discovery

When to use

• User wants to know what to provision in dispatch layer for a service
• User asks "what services/modules/resources does this project have?"
• Before running ring:adding-multi-tenancy on a new service
• User asks about MongoDB indexes in a project

Skip when

• Not a Go project
• Task does not involve service discovery, dispatch layer, or resource mapping
• Project has no external dependencies

Related

**Complementary:** ring:adding-multi-tenancy, ring:implementing-tasks

Prerequisites

• Go project with go.mod in the current working directory

Scans Go project to produce dispatch layer registration data. Orchestrator executes all detection phases directly.

Phase 1: Service Detection

# Service name
grep "ApplicationName\|ServiceName" internal/bootstrap/config.go 2>/dev/null | head -5
cat .env.example 2>/dev/null | grep -i "APPLICATION_NAME\|SERVICE_NAME" | head -3

# Service type
test -f go.mod && cat go.mod | head -3  # module path hints service purpose
ls internal/adapters/ 2>/dev/null       # adapters reveal type

# Unified service check
ls components/ 2>/dev/null              # multiple components = unified service

Output:

service_name: "my-service"
is_unified: true | false
components: [{name, path, applicationName}]  # if unified

Phase 2: Module Detection

# Strategy A: Explicit WithModule calls (preferred)
grep -rn "WithModule(" internal/ components/ 2>/dev/null
# Extract string arg: WithModule("onboarding") → module "onboarding"

# Strategy B: Component-based (if no WithModule found)
ls components/  # each component = one module
# module_name = component's ApplicationName

# Strategy C: Single-component fallback
# module_name = service ApplicationName

Merge: Strategy A → B fills gaps → C fallback.

Phase 3: Resource Detection per Module

For each module, scan `{component_path}/internal/adapters/`:

# PostgreSQL: subdirectory existence
ls {base_path}postgres/ 2>/dev/null

# MongoDB
ls {base_path}mongodb/ 2>/dev/null || ls {base_path}mongo/ 2>/dev/null

# RabbitMQ
ls {base_path}rabbitmq/ 2>/dev/null
grep -l "producer\|Producer" {base_path}rabbitmq/ 2>/dev/null
grep -l "consumer\|Consumer" {base_path}rabbitmq/ 2>/dev/null

# Redis (informational only — NOT a dispatch layer resource)
ls {base_path}redis/ 2>/dev/null

Phase 3.5: Database Name Detection per Module

# From bootstrap config
grep -E 'env:"POSTGRES_NAME|env:"DB_.*_NAME|env:"MONGO_NAME|env:"MONGO_.*_NAME' \
  {component_path}/internal/bootstrap/config.go

# From .env.example (actual values)
grep -E "POSTGRES_NAME=|DB_.*_NAME=|MONGO_NAME=|MONGO_.*_NAME=" {component_path}/.env.example

# External datasources
grep -E "DATASOURCE_.*_DATABASE=" {component_path}/.env.example

Cross-reference across modules: same database name in 2+ modules = shared (provision once).

Phase 4: MongoDB Index Detection & Migration File Generation

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

Execute the procedure in `references/mongodb-index-detection.md` — Steps 1, 2, 3, 4 only. (Detection and local generation only; S3 upload is handled in Phase 6.)

1. **Step 1** — Detect in-code index definitions (`EnsureIndexes`, `IndexModel`, `CreateIndex`) per module. 2. **Step 2** — Detect existing local migration files in `{component_path}/scripts/mongodb/*.up.json` + `*.down.json` (fallback legacy `*.js`). LOCAL ONLY — no S3 lookup. 3. **Step 3** — Cross-reference code vs. local migration files, classify each as `covered` / `missing_migration` / `migration_only`. 4. **Step 4** — Generate one `.up.json` + `.down.json` file pair per missing index (atomic per index, NOT grouped by collection):

• Path: `{component_path}/scripts/mongodb/{NNNNNN}_{index_name}.up.json` / `.down.json` — per-module directory preserves ownership for Phase 6 upload (single-component services resolve `{component_path}` to repo root)
• Naming: `idx_{collection}_{fields}` (or `uniq_*` for uniqueness business rules)
• HARD GATE: every `.up.json` MUST have explicit `"options.name"` matching the file name
• **Track per module:** populate `module.generated_migration_files = [{up_file, down_file, index_name}, ...]` so Phase 6 knows exactly which files belong to which module

**Format reminder:** the dispatch layer reads `.up.json` / `.down.json` from S3 and applies indexes on tenant provisioning. The service does NOT execute these files. Legacy `.js` scripts are NOT uploaded — only JSON migrations.

Phase 4.5: PostgreSQL Migration Detection

**Only execute if PostgreSQL was detected in any module during Phase 3.**

Detection only — Postgres migrations are written by developers; this skill does NOT generate `.sql` files.

# Common golang-migrate locations (per module path resolved in Phase 3)
ls {component_path}/scripts/postgres/*.up.sql 2>/dev/null
ls {component_path}/scripts/postgresql/*.up.sql 2>/dev/null
ls {component_path}/db/migrations/*.up.sql 2>/dev/null
ls {component_path}/migrations/*.up.sql 2>/dev/null

For each `.up.sql` file found:

• Verify the matching `.down.sql` exists (golang-migrate convention).
• Map it to its module (by directory path).
• Track for the Phase 6 upload.

Store: `module.postgres_migrations = [{up_file, down_file, sequence, description}]`

If a `.up.sql` exists without `.down.sql` → flag in Phase 5 HTML report (golang-migrate requires pairs).

Phase 5: Generate HTML Report

Dispatch `ring:visualizing