Distributed Systems 7 min read Sep 2024 ArchMCP

Before You Break Production: Mapping Cross-Service Dependencies in Microservices

Why grep misses breaking changes in distributed systems, and how ArchMCP links HTTP calls, Kafka topics, background jobs, and Docker configs to warn you before you deploy.

Shubham Upadhyay

Senior Backend & Systems Engineer

01.

The Illusion of Isolated Services: Why Grep Misses Breaking Changes

In a monolithic codebase, when you want to rename a function or modify a parameter type, your IDE's language server immediately underlines every broken caller in red. You fix them, run your test suite, and you're good to go.

In microservices, you completely lose that safety net.

Suppose you're working on order-service and you decide to clean up an older route from /api/v1/orders/checkout to /api/v1/orders/process-payment. You search your repository, find zero other references, and commit with confidence.

What you don't know is that mobile-api-gateway calls that endpoint using a constructed environment variable (ORDER_SVC_URL + '/api/v1/orders/checkout'). You also don't know that notification-service is listening to an asynchronous Kafka event published by that route, and a background worker in fraud-detection expects the old payload structure.

None of those services share your repository, your build tool, or your programming language. One is in Go, another in TypeScript, and another in Python. Traditional search tools like grep and ripgrep can't see the connection because they only match literal text in the current folder. The change passes your local tests, gets merged, and causes an outage the minute it hits staging.

"In microservices, breaking changes don't announce themselves with compiler errors. They deploy silently and wake you up at 2 AM."

— Shubham Upadhyay

02.

Beyond HTTP: The 4 Connection Signals We Track

When designing the dependency linker in ArchMCP (src/archmcp/discovery/dependency_linker.py), we realized that looking only for hardcoded REST URLs misses more than half of real-world service interactions. We structured the discovery engine around four complementary signals:

Synchronous Direct Connections

Code-Level HTTP Clients: Parses AST and call patterns for Python (requests, httpx), Node/TS (axios, fetch), and Go (http.Client).
Inter-Service Environment Variables: Matches configurations like AUTH_SERVICE_HOST, PAYMENT_GATEWAY_URL, or INVENTORY_ADDR.
Container Links: Extracts depends_on service graphs and internal Docker bridge networks from docker-compose.yml.
OpenAPI Contracts: Correlates exported Swagger/OpenAPI schemas against client consumer paths.

Asynchronous Indirect Contracts

Event Topic Matching: Pairs services marked as producer on a Kafka topic or RabbitMQ exchange with services marked as consumer.
Background Task Queues: Identifies async task publishers and workers (e.g. Celery queues, BullMQ, Temporal).
Shared Database Tables: Flags when two distinct microservices read from or write to the same database entities.
Automatic Edge Inference: Converts all four signals into a unified, directed dependency graph (DAG) in memory.

03.

From Polyglot Source Code to Live Architecture Graph

The linking process happens entirely during the discovery pass. Instead of requiring developers to manually write architecture YAML files that go out of date in a week, ArchMCP derives the topology directly from code artifacts.

HOW ARCHMCP DERIVES CROSS-SERVICE CONTRACTS IN REAL TIME

1 Polyglot AST & Code Scan → Discovers routes, client calls, queues, and configs

2 Multi-Modal Dependency Linker → Correlates HTTP, Kafka topics, env vars & Docker

3 Caller Graph Construction → Builds bidirectional adjacency lists in memory

4 BFS Transitive Traversal → Traces multi-hop ripples across downstream consumers

5 Mermaid & ASCII Synthesis → Renders visual sequence flows and risk scores

04.

The Blast Radius Engine: Calculating Ripple Effects with BFS

Direct callers are only half the battle. If Service A breaks Service B, and Service B is the primary data feed for Service C and Service D, modifying Service A has a ripple effect that touches four different engineering teams.

To calculate this without writing slow recursive database queries, ArchMCP implements a Breadth-First Search (BFS) engine in services/architecture_service.py.

When queried for a specific service or endpoint, it builds a reverse caller graph, pushes direct consumers into a queue, and explores the transitive closure until every indirect subscriber is mapped.

Based on the depth of the tree, critical services involved (such as auth-service), and the total number of impacted consumers, ArchMCP calculates a risk severity rating (LOW, MEDIUM, HIGH, or CRITICAL) and outputs actionable guidance.

src/archmcp/services/architecture_service.py

BFS Ripple Analyzer

# Build reverse caller adjacency graph (callee -> list of callers)
caller_graph: Dict[str, Set[str]] = {s_id: set() for s_id in all_services}
for s_id, s_data in all_services.items():
    for upstream_id in s_data.dependencies.upstream:
        if upstream_id in caller_graph:
            caller_graph[upstream_id].add(s_id)

# BFS to discover direct and transitive multi-hop callers
direct_callers: Set[str] = set(caller_graph.get(service_id, set()))
transitive_callers: Set[str] = set()
visited: Set[str] = {service_id}.union(direct_callers)
queue = deque(list(direct_callers))

while queue:
    curr = queue.popleft()
    for next_caller in caller_graph.get(curr, set()):
        if next_caller not in visited:
            visited.add(next_caller)
            transitive_callers.add(next_caller)
            queue.append(next_caller)

# Calculate severity score based on blast radius
total_dependents = len(direct_callers) + len(transitive_callers)
if service_id == "auth-service" or total_dependents >= 3:
    severity = "CRITICAL"
elif total_dependents >= 2 or len(transitive_callers) > 0:
    severity = "HIGH"
else:
    severity = "LOW"

05.

Giving the AI a Visual Sequence Diagram (Mermaid on Demand)

Text descriptions of distributed workflows get confusing very quickly. When an AI coding assistant or a developer asks: "Show me what the checkout flow looks like", ArchMCP dynamically assembles a standard Mermaid sequence diagram from the dependency graph.

What the Developer Sees in the Visualizer

Clean, numbered sequence diagrams showing exact request and response lifecycles.
Distinct swimlanes for every participating service (auth-service, order-service, payment-service, inventory-service).
Clear visual distinction between synchronous HTTP REST calls and asynchronous Kafka events.
Instant visual clarity on which service initiates the call and which service responds.

What the AI Assistant Receives via MCP

Structured Mermaid syntax that modern AI models (Claude, Cursor, Antigravity) parse natively.
List of all participating service IDs and owning engineering teams.
Eliminates hallucinations by anchoring the AI's reasoning to verified inter-service paths.
Context is compact (~200 tokens) yet conveys the entire end-to-end distributed transaction.

06.

Engineering Takeaways

Asynchronous Contracts Are Where Outages Hide

HTTP endpoints are relatively easy to spot. Message queues, Kafka topics, and shared database tables are where the most damaging silent breaking changes occur.

Derive Architecture from Code, Not Documentation

Architecture documentation is obsolete the week after it is written. Scanning live code, configs, and containers ensures the graph always reflects reality.

Multi-Hop Visibility Protects Downstream Teams

Knowing direct callers is good; knowing the third-hop consumer prevents cross-department firefighting during releases.

Compact Graph Context Beats Raw Code Every Time

Handing an AI assistant a 15-line BFS ripple summary prevents far more regressions than pasting 5,000 lines of unindexed source code.

Explore Further

Want to review the full ArchMCP overview?

Check out technical architecture, problems faced, and complete tech stack.

View Project Overview