Microservices Architect Agent

A senior microservices architect specializing in distributed system design with deep expertise in Kubernetes, service mesh technologies, and cloud-native patterns for building scalable, resilient, and maintainable microservice architectures.

When to Use This Agent

Choose Microservices Architect Agent when:

• Designing microservice boundaries and communication patterns
• Implementing service mesh, API gateway, and inter-service communication
• Planning monolith-to-microservices migration strategies
• Designing event-driven architectures with message brokers
• Solving distributed system challenges (consistency, transactions, failures)

Consider alternatives when:

• Building a single monolithic application (a monolith may be the right choice)
• Managing Kubernetes operations (use Kubernetes Specialist Mentor)
• Designing cloud infrastructure (use Guide Cloud Architect)

Quick Start

Copy
# .claude/agents/microservices-architect-agent.yml
name: Microservices Architect Agent
description: Design distributed microservice architectures
model: claude-sonnet
tools:
  - Read
  - Write
  - Glob
  - Grep
  - WebSearch

Example invocation:

claude "Design the microservice architecture for an e-commerce platform, defining service boundaries, communication patterns, and data ownership"

Core Concepts

Service Boundary Design

Domain	Service	Owns Data	Key APIs
Users	User Service	users, profiles	CRUD users, auth tokens
Products	Catalog Service	products, categories	Search, browse, details
Orders	Order Service	orders, line items	Create, status, history
Payments	Payment Service	transactions	Charge, refund, status
Inventory	Inventory Service	stock levels	Reserve, release, check
Notifications	Notification Service	preferences, templates	Send email, SMS, push

Communication Patterns

Copy
## Synchronous (Request-Reply)
- REST/gRPC between services needing immediate responses
- API Gateway → Service (external requests)
- Service → Service (queries, reads)

## Asynchronous (Event-Driven)
- Events published to message broker (Kafka, RabbitMQ)
- Eventual consistency between service data stores
- Best for: order processing, notifications, analytics

## Pattern Selection
| Need | Pattern | Example |
|------|---------|---------|
| Immediate response | Sync (gRPC) | Get user profile |
| Fire and forget | Async event | Send notification |
| Data consistency | Saga pattern | Multi-service transaction |
| Data aggregation | API composition | Order details + user + items |

Saga Pattern for Distributed Transactions

Copy
// Choreography-based saga for order creation
// Each service publishes events, others react

// Order Service
async function createOrder(orderData: CreateOrderInput) {
  const order = await db.orders.create({ ...orderData, status: 'pending' });
  await eventBus.publish('order.created', {
    orderId: order.id,
    items: order.items,
    userId: order.userId,
    paymentMethod: orderData.paymentMethod,
  });
  return order;
}

// Inventory Service listens for order.created
eventBus.subscribe('order.created', async (event) => {
  try {
    await reserveInventory(event.items);
    await eventBus.publish('inventory.reserved', { orderId: event.orderId });
  } catch (error) {
    await eventBus.publish('inventory.reservation-failed', {
      orderId: event.orderId,
      reason: error.message,
    });
  }
});

// Payment Service listens for inventory.reserved
eventBus.subscribe('inventory.reserved', async (event) => {
  try {
    await processPayment(event.orderId);
    await eventBus.publish('payment.completed', { orderId: event.orderId });
  } catch (error) {
    await eventBus.publish('payment.failed', { orderId: event.orderId });
    // Compensating action: release inventory
    await eventBus.publish('inventory.release-requested', { orderId: event.orderId });
  }
});

Configuration

Parameter	Description	Default
communication	Default inter-service protocol (rest, grpc, graphql)	grpc
messaging	Event/message broker (kafka, rabbitmq, sqs)	kafka
service_mesh	Service mesh (istio, linkerd, none)	none
api_gateway	API gateway (kong, ambassador, envoy)	kong
data_strategy	Data ownership (database-per-service, shared)	database-per-service
consistency	Consistency model (eventual, strong, saga)	eventual

Best Practices

1. Define service boundaries around business capabilities, not technical layers. A "User Service" that owns user registration, authentication, profiles, and preferences is better than separate "Auth Service," "Profile Service," and "Preferences Service." Each service should align with a bounded context from Domain-Driven Design: a coherent domain with clear boundaries, its own data model, and its own team.

2. Each service owns its data — no shared databases between services. If the Order Service needs user data, it calls the User Service API or maintains a local read-only copy via events. Shared databases create tight coupling: schema changes in one service break others, and locking contention creates performance interdependencies. Database-per-service is the fundamental principle that enables independent deployability.

3. Use asynchronous events for operations that do not need immediate responses. Sending a confirmation email, updating analytics, notifying partner systems — none of these need to complete before responding to the user. Publish events and let downstream services process them at their own pace. This decouples services, improves response times, and provides natural resilience when downstream services are temporarily unavailable.

4. Implement the strangler fig pattern for monolith-to-microservices migration. Do not rewrite the monolith from scratch. Extract one bounded context at a time behind an API gateway. Route traffic for that context to the new microservice while the monolith handles everything else. Gradually strangle the monolith by extracting more contexts. Each extraction is independently deployable and reversible.

5. Design for failure at every service boundary. When Service A calls Service B, B may be slow, down, or returning errors. Implement circuit breakers (stop calling after N failures), timeouts (do not wait forever), retries with backoff (handle transient failures), and fallbacks (return cached data or degraded response). Without these patterns, one failing service cascades failures to all dependent services.

Common Issues

Distributed transactions across services lead to data inconsistency. Traditional ACID transactions do not work across service boundaries. Use the Saga pattern: a sequence of local transactions with compensating actions for rollback. Choose choreography (events) for simple flows and orchestration (central coordinator) for complex flows. Accept eventual consistency and design the UI to communicate pending states to users.

Service-to-service communication creates a distributed monolith. If deploying Service A requires deploying Services B, C, and D simultaneously, you have a distributed monolith — the worst of both worlds. This happens when services share too many synchronous dependencies or when API contracts change without versioning. Design services to be independently deployable with backward-compatible API changes and event-driven coupling.

Debugging across microservices is significantly harder than in a monolith. A single user request may span 5-10 services, making it difficult to trace failures. Implement distributed tracing (OpenTelemetry, Jaeger) that propagates trace IDs across all service calls. Centralize logs with correlation IDs. Build a service dependency map that shows communication patterns and failure rates. Without these tools, debugging microservices is like solving a puzzle blindfolded.