Service Mapper

Analyze a codebase and produce a structured, AI-agent-friendly service map. The output documents every microservice, how they communicate, what databases and tables they own, and what external systems they integrate with.

When to Use

• Onboarding to an unfamiliar codebase
• Generating or updating a CLAUDE.md or SERVICE-MAP.md
• Before planning a new feature (understand what exists)
• Auditing service boundaries and ownership
• Detecting architectural violations (shared DBs, direct HTTP between services, etc.)
• After significant refactoring to verify the architecture still makes sense

Workflow

Execute these steps in order. Each step builds on the previous.

Step 1: Identify Service Boundaries

Scan the repository structure to find all deployable units (services, workers, lambdas, cron jobs).

What to look for:

For each service, record:

• Name
• Language / framework
• Entrypoint file
• Port (if HTTP)
• Type: webservice | worker | cron | lambda | gateway

Step 2: Map Inter-Service Communication

For each service, trace how it talks to other services.

Communication patterns to detect:

For each connection, record:

• Source service
• Target service
• Protocol (HTTP / AMQP / gRPC / SDK / etc.)
• Direction (unidirectional / request-response / pub-sub)
• What data flows (event names, endpoint paths, RPC methods)

Step 3: Map Database Ownership

Identify every database, schema, or table and determine which service owns it.

What to look for:

For each data store, record:

• Type (PostgreSQL, MongoDB, Redis, S3, etc.)
• Tables / collections (list them)
• Owner service (the service that writes to it)
• Reader services (services that read from it — directly or via gateway)
• Access pattern: direct | via-gateway-service | via-message-bus

Flag violations:

• Multiple services writing to the same table (shared mutable state)
• Services bypassing a DB gateway to access the database directly
• No clear owner for a table

Step 4: Map External Integrations

Find every connection to systems outside the codebase.

What to look for:

For each integration, record:

• External system name (e.g., Stripe, SendGrid, S3)
• Which service connects to it
• Direction: outbound (we call them) | inbound (they call us) | bidirectional
• Auth method (API key, OAuth, mTLS, etc.)
• Data exchanged (what we send/receive)

Step 5: Trace Event Flows

For event-driven architectures, map the full lifecycle of key events.

For each event type:

• Publisher (which service emits it)
• Subscribers (which services consume it)
• Payload schema (or reference to contract)
• What triggers the event
• What downstream effects it causes

Build 3-5 critical flow diagrams showing end-to-end event chains (e.g., "user action → ingestion → processing → storage → notification").

Step 6: Generate the Service Map

Produce the output document using the structure in TEMPLATES.md.

Discovery Commands

Use these to accelerate analysis. Adapt to the project's language/framework.

Find entrypoints

# Go
find . -name "main.go" -not -path "*/vendor/*"

# Node/TypeScript
find . -name "index.ts" -path "*/src/*" -not -path "*/node_modules/*"

# Python
find . -name "main.py" -o -name "app.py" -o -name "wsgi.py" | grep -v __pycache__

Find message bus usage

# RabbitMQ / AMQP
grep -rn "publish\|subscribe\|consume\|createChannel\|assertQueue\|assertExchange" --include="*.ts" --include="*.go" --include="*.py"

# Kafka
grep -rn "producer\|consumer\|KafkaClient\|kafka.NewReader\|kafka.NewWriter" --include="*.ts" --include="*.go" --include="*.py"

# Event type constants
grep -rn "EVENT_TYPE\|event_type\|EventType\|ROUTING_KEY\|routing_key" --include="*.ts" --include="*.go" --include="*.py"

Find database access

# Table names in SQL
grep -rn "FROM \|INTO \|UPDATE \|CREATE TABLE\|ALTER TABLE" --include="*.ts" --include="*.go" --include="*.py" --include="*.sql"

# ORM models
grep -rn "Entity\|@Table\|@Model\|tableName\|__tablename__" --include="*.ts" --include="*.py" --include="*.java"

# DB connection setup
grep -rn "DATABASE_URL\|SUPABASE_URL\|MONGO_URI\|createConnection\|createPool\|getConnection" --include="*.ts" --include="*.go" --include="*.py" --include="*.env*"

Find external API calls

# HTTP clients
grep -rn "axios\|fetch(\|http.Get\|http.Post\|requests.get\|requests.post\|HttpClient" --include="*.ts" --include="*.go" --include="*.py"

# API keys in env
grep -rn "API_KEY\|API_SECRET\|_TOKEN\|_SECRET" --include="*.env*" --include="*.yaml" --include="*.ts"

Find deployment configs

# Docker
find . -name "Dockerfile" -o -name "docker-compose*.yaml" -o -name "docker-compose*.yml"

# Kubernetes
find . -name "*.yaml" -path "*/k8s/*" -o -name "*.yaml" -path "*/deploy*/*"

# Serverless
find . -name "serverless.yml" -o -name "serverless.ts"

# Cloud platform
find . -name "app.yaml" -o -name "app.spec.yaml" -o -name "*.tf"

Quality Checks

Before presenting the service map, verify:

• Every service has a clear type (webservice/worker/cron/lambda/gateway)
• Every inter-service connection has protocol and direction documented
• Every database table has exactly one owner service identified
• Every external integration has the connecting service identified
• No orphan services (services with zero connections — likely missed something)
• Event flows cover the critical business paths
• ASCII diagrams are present for high-level architecture and key flows
• The map is self-contained — an AI agent can understand the architecture without reading code

Supporting Files

• TEMPLATES.md — Output format and examples for the service map