Using Claude Code and GitNexus with Multi-Service Systems

Modern software systems rarely live in a single repository. When working with microservices, you're dealing with multiple codebases, different tech stacks, and complex dependencies between services. This is where Claude Code combined with GitNexus becomes incredibly powerful.

The Challenge: Multi-Service Architectures

Let me show you a real-world example: an e-commerce platform with 6 services and an external dependency.

System Overview

Our e-commerce platform consists of:

Frontend: React 18 with Next.js 14 (Port 3000)

API Gateway: Node.js + Express (Port 8080)

Auth Service: Node.js + JWT (Port 8081)

Payment Service: Python + FastAPI (Port 8082)

Media Service: Go (Port 8083)

Product Service: Java + Spring Boot (Port 8084)

PDF Export Service: External microservice (Port 9000)

The Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                             │
│                  (React/Next.js SPA)                         │
│                    Port: 3000                                │
└──────────┬──────────┬──────────┬──────────┬────────────────┘
           │          │          │          │
           ▼          ▼          ▼          ▼
    ┌──────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐
    │   API    │ │  Auth   │ │ Payment │ │  Media   │
    │ Gateway  │ │ Service │ │ Service │ │ Service  │
    │          │ │         │ │         │ │          │
    │ Port:    │ │ Port:   │ │ Port:   │ │ Port:    │
    │  8080    │ │  8081   │ │  8082   │ │  8083    │
    └────┬─────┘ └────┬────┘ └────┬────┘ └────┬─────┘
         │            │           │           │
         ▼            │           │           │
    ┌─────────────┐  │           │           │
    │  Product    │  │           │           │
    │  Service    │  │           │           │
    │             │  │           │           │
    │  Port: 8084 │  │           │           │
    └──────┬──────┘  │           │           │
           │         │           │           │
           ▼         ▼           ▼           ▼
    ┌──────────────────────────────────────────┐
    │         Shared PostgreSQL DB             │
    │              Port: 5432                  │
    └──────────────────────────────────────────┘

Real-World Example: The Purchase Flow

When a user makes a purchase, here's what happens:

Frontend → API Gateway → Auth Service: Validates user token

Frontend → API Gateway → Product Service: Fetches product details, checks inventory

Frontend → API Gateway → Payment Service: Processes payment

Payment Service → PDF Export Service: Generates invoice PDF

Payment Service → Media Service: Stores invoice PDF

API Gateway → Frontend: Returns order confirmation

A simple purchase involves 6 services across different tech stacks. How do you safely refactor code when a single change can ripple across this entire system?

Enter GitNexus: Your Multi-Repo Code Intelligence

GitNexus indexes multiple repositories and builds a knowledge graph that understands:

Cross-service dependencies: Which services call which endpoints

API contracts: The interfaces between services

Execution flows: How requests travel through your system

Impact analysis: What breaks when you change something

Setting Up GitNexus for Multiple Projects

First, index all your repositories:

# Index each service
cd ecommerce-frontend && npx gitnexus analyze
cd ../ecommerce-api-gateway && npx gitnexus analyze
cd ../ecommerce-auth-service && npx gitnexus analyze
cd ../ecommerce-payment-service && npx gitnexus analyze
cd ../ecommerce-media-service && npx gitnexus analyze
cd ../ecommerce-product-service && npx gitnexus analyze

Now GitNexus knows about all your services and their relationships.

Using Claude Code with GitNexus

Example 1: Understanding Cross-Service Impact

Let's say you want to change the payment processing logic. Before making any changes, ask Claude Code:

"What's the impact of changing the processPayment function in the payment service?"

Claude Code will use GitNexus to:

Find all callers of processPayment (API Gateway, frontend)

Identify downstream services (PDF Export, Media Service)

Show which execution flows are affected

Flag the risk level (HIGH, CRITICAL, etc.)

Example 2: Tracing a Bug Across Services

User reports: "My invoice PDF isn't being generated." With Claude Code + GitNexus:

"Trace the invoice generation flow from the payment service"

Claude Code will map out:

Payment Service calls /export-pdf on PDF Export Service

PDF Export Service returns PDF bytes

Payment Service uploads to Media Service

Any failure points in the chain

Example 3: Safe Refactoring

You need to rename an API endpoint from /api/v1/products to /api/v2/products:

"Help me rename the products endpoint safely across all services"

Claude Code with GitNexus will:

Find all references to this endpoint (API Gateway routes, frontend API calls, product service handlers)

Show which services need updates

Generate a migration plan with backward compatibility

Verify no execution flows are broken

Best Practices for Multi-Service Development

1. Always Run Impact Analysis

Before editing any function that's called by other services:

# Claude Code automatically does this when you have CLAUDE.md configured
"What breaks if I change the authenticateUser function?"

2. Check Cross-Repo Changes

Before committing:

# In each affected repo
npx gitnexus detect-changes

This shows which symbols changed and which execution flows are affected.

3. Map Your API Contracts

Use GitNexus to understand service boundaries:

npx gitnexus api-impact --target payment-service

This shows all the APIs the payment service exposes and who calls them.

4. Visualize Execution Flows

See how requests flow through your system:

# Ask Claude Code
"Show me the execution flow for user checkout"

The Technology Stack

Here's what we're working with:

Component	Technology
Frontend	React 18, Next.js 14, TypeScript
API Gateway	Node.js, Express
Auth Service	Node.js, Express, JWT
Payment Service	Python, FastAPI
Product Service	Java, Spring Boot
Media Service	Go, Gin Framework
PDF Export	Node.js, Puppeteer
Database	PostgreSQL 15
Message Queue	RabbitMQ
Cache	Redis

Different languages, different paradigms, but GitNexus understands them all.

Common Challenges Solved

1. Breaking Changes

Problem: You update an API response format in the Product Service, breaking the frontend.

Solution: GitNexus tracks API contracts. Claude Code warns you before you push:

⚠️  HIGH RISK: Changing ProductResponse type affects 12 callers in ecommerce-frontend

2. Hidden Dependencies

Problem: The Payment Service calls PDF Export Service, which you didn't know about.

Solution: GitNexus maps all service-to-service calls. Query it:

"What external services does payment-service depend on?"

3. Debugging Distributed Systems

Problem: A request fails somewhere in the chain, but logs are scattered.

Solution: GitNexus traces execution flows:

"Trace the failed request ID abc-123 through all services"

4. Refactoring Fear

Problem: You want to refactor the Auth Service but don't know what will break.

Solution: Run impact analysis first:

gitnexus impact --target generateJWT --direction upstream

Shows you every service that depends on that function.

Deployment with Docker Compose

Here's how we run the whole system locally:

# docker-compose.yml
services:
  frontend:
    build: ./ecommerce-frontend
    ports: ["3000:3000"]
    
  api-gateway:
    build: ./ecommerce-api-gateway
    ports: ["8080:8080"]
    
  auth-service:
    build: ./ecommerce-auth-service
    ports: ["8081:8081"]
    
  payment-service:
    build: ./ecommerce-payment-service
    ports: ["8082:8082"]
    
  media-service:
    build: ./ecommerce-media-service
    ports: ["8083:8083"]
    
  product-service:
    build: ./ecommerce-product-service
    ports: ["8084:8084"]
    
  pdf-export:
    build: ./pdf-export-service
    ports: ["9000:9000"]
    
  postgres:
    image: postgres:15
    ports: ["5432:5432"]

Configuring Claude Code for Multi-Service Projects

Add this to each service's CLAUDE.md:

# GitNexus — Code Intelligence

This project is indexed by GitNexus as **ecommerce-payment-service**.

## Always Do

- **MUST run impact analysis before editing any symbol**
- **MUST check cross-service dependencies before refactoring**
- **MUST run `gitnexus detect-changes()` before committing**
- **MUST warn me if impact analysis returns HIGH or CRITICAL risk**

## Service Dependencies

This service depends on:
- PDF Export Service (external) for invoice generation
- Media Service for storing invoice files
- Auth Service for token validation

## Resources

| Resource | Use for |
|----------|---------|
| `gitnexus://repo/payment-service/context` | Codebase overview |
| `gitnexus://repo/payment-service/processes` | All execution flows |

Conclusion

Working with microservices doesn't have to be scary. With Claude Code and GitNexus, you get:

Confidence: Know exactly what your changes will affect

Speed: Navigate complex systems without mental overhead

Safety: Catch breaking changes before they reach production

Clarity: Understand execution flows across service boundaries

The combination of Claude Code's AI assistance and GitNexus's code intelligence makes managing multi-service architectures not just manageable, but enjoyable.

Start with one service, index it with GitNexus, and let Claude Code guide you through the rest. Your future self (and your team) will thank you.

Resources

GitNexus Documentation

Claude Code

GitNexus Skills for Claude Code

---

Got questions about using Claude Code with your microservices? Reach out on Twitter @yudinugraha