Service Dependency Map Template

Overview

In distributed systems, a failure in one service can cascade unpredictably. A dependency map documents which services call which, the nature of those calls, and the blast radius if a dependency fails. This template provides both a textual registry and guidance for creating visual diagrams.

When to Use

Use this resource when:

• Onboarding a new service and documenting its upstream and downstream relationships
• Planning a migration, deprecation, or infrastructure change
• Conducting failure mode and effects analysis (FMEA)

Solution

# Service Dependency Map: `<Service Name>`

## 1. Service Metadata

| Field | Value |
|-------|-------|
| Service | `name` |
| Owner Team | `@team-name` |
| Repository | `github.com/org/repo` |
| Runtime | `Kubernetes / ECS / Lambda / VM` |
| Last Updated | `YYYY-MM-DD` |

## 2. Upstream Dependencies (This Service Consumes)

| Service | Protocol | Endpoint / Topic | Purpose | Critical? | Fallback |
|---------|----------|------------------|---------|-----------|----------|
| user-service | HTTP | GET /users/{id} | Auth validation | Yes | Cache for 5 min |
| payment-service | gRPC | Charge() | Process payment | Yes | Queue for retry |
| notification-service | Event | `notify.send` | Send email | No | Skip silently |
| analytics-service | HTTP | POST /events | Track metrics | No | Drop (best effort) |

## 3. Downstream Dependencies (Services Consuming This)

| Service | Protocol | Endpoint / Topic | Purpose | Rate Limit |
|---------|----------|------------------|---------|------------|
| web-frontend | HTTP | GET /api/products | Product catalog | 1,000/min |
| mobile-app | HTTP | GET /api/products | Product catalog | 500/min |
| inventory-service | Event | `inventory.update` | Stock changes | 10,000/hr |

## 4. External Dependencies

| Vendor | Service | Purpose | SLA | Escalation |
|--------|---------|---------|-----|------------|
| Stripe | Payment API | Process cards | 99.9% | support@stripe.com |
| SendGrid | Email API | Transactional email | 99.9% | status.sendgrid.com |
| AWS S3 | Object storage | File uploads | 99.99% | AWS Support |

## 5. Critical Path Analysis

| Flow | Services Involved | Max Acceptable Latency | Risk if Broken |
|------|-------------------|------------------------|----------------|
| Checkout | web → cart → payment → user | 2s | Revenue loss |
| Login | web → user → session-cache | 500ms | User lockout |
| Search | web → search → product-db | 1s | Degraded UX |

## 6. Failure Impact Matrix

| Dependency Fails | Direct Impact | Cascading Impact | Mitigation |
|------------------|---------------|------------------|------------|
| payment-service | Cannot checkout | No revenue | Queue + retry + alert |
| user-service | Cannot authenticate | All flows stop | Cached JWT + degraded mode |
| notification-service | Emails delayed | No cascading | Skip + audit log |

## 7. Diagram Representation

[web-frontend] ──→ [product-service] ──→ [product-db] │ ↓ [payment-service] ←── [Stripe] │ ↓ [notification-service] ──→ [SendGrid]

- Use C4 diagrams or dependency graphs (Graphviz, Mermaid, Lucidchart)
- Color code: green (healthy), yellow (degraded), red (outage), gray (planned removal)

Explanation

The map separates upstream (what the service needs) from downstream (what needs the service). Criticality flags highlight which failures require immediate attention. The failure impact matrix answers “what breaks and how badly?” before incidents happen. External dependencies get their own section because vendor SLAs are outside your control. The diagram provides a visual summary for architecture reviews.

Variants

Context	Approach	Notes
Startup	Simple table + Mermaid diagram	Keep it in the service README
Enterprise	C4 diagrams + CMDB integration	Use tools like ServiceNow or Backstage
Serverless	Add function-level granularity	Map individual Lambdas to triggers and destinations

Best Practices

1. Update the map after every architectural change, not just quarterly
2. Store maps in version control alongside service code
3. Mark dependencies as deprecated before removing them, with target removal dates
4. Include rate limits and quotas for downstream services to prevent accidental overload
5. Link each dependency to its microservice contract or runbook for fast reference

Common Mistakes

1. Documenting only synchronous HTTP calls and ignoring async event dependencies
2. Treating all dependencies as equally critical, masking the real blast radius
3. Creating diagrams that are too detailed to read in a single screen
4. Not updating maps after refactors, making them untrusted
5. Omitting third-party services because “they are someone else’s problem”

Frequently Asked Questions

What tool should I use to draw dependency maps?

Mermaid.js works well in Markdown and wikis. Lucidchart and draw.io are better for presentations. For automated discovery, use Datadog Service Map, AWS X-Ray, or OpenTelemetry service graphs.

How do I keep maps current without manual updates?

Use distributed tracing (Jaeger, Zipkin) to auto-discover call graphs. Export trace topology into a living diagram that updates with each deployment.

Should I include databases and caches as dependencies?

Yes. Databases and caches are critical infrastructure dependencies. Include them with their type (PostgreSQL, Redis, DynamoDB) and any connection pool or replication details that affect failover.