hivemind: Skill for Claude Code

Microservices Architecture Patterns

Service Structure

services/
  api-gateway/          # Entry point, routing, auth
  user-service/         # User management, auth
  product-service/      # Products, catalog, inventory
  order-service/        # Orders, checkout flow
  notification-service/ # Email, push, SMS (event-driven)
  payment-service/      # Stripe, billing
shared/
  proto/                # gRPC definitions (if used)
  events/               # Event schemas (Pydantic/TypeScript)
  libs/                 # Shared utilities
docker-compose.yml

API Gateway (FastAPI)

# api-gateway/main.py
import httpx
from fastapi import FastAPI, Request, Depends, HTTPException
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"])

SERVICE_URLS = {
    "users": "http://user-service:8001",
    "products": "http://product-service:8002",
    "orders": "http://order-service:8003",
}

@app.api_route("/{service}/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH"])
async def proxy(service: str, path: str, request: Request, user=Depends(verify_token)):
    if service not in SERVICE_URLS:
        raise HTTPException(404, "Service not found")

    url = f"{SERVICE_URLS[service]}/{path}"
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method=request.method,
            url=url,
            headers={"X-User-Id": str(user.id), "X-User-Role": user.role},
            content=await request.body(),
            params=dict(request.query_params),
            timeout=30,
        )
    return Response(content=response.content, status_code=response.status_code,
                   media_type=response.headers.get("content-type"))

Inter-Service Communication

Synchronous (HTTP)

# Shared HTTP client with circuit breaker
import httpx
from tenacity import retry, stop_after_attempt, wait_exponential

class ServiceClient:
    def __init__(self, base_url: str):
        self.client = httpx.AsyncClient(base_url=base_url, timeout=10)

    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=10))
    async def get(self, path: str, **kwargs):
        response = await self.client.get(path, **kwargs)
        response.raise_for_status()
        return response.json()

# order-service calling user-service
user_client = ServiceClient("http://user-service:8001")

async def get_order_with_user(order_id: str):
    order = await db.orders.find_one(order_id)
    user = await user_client.get(f"/users/{order['user_id']}")  # Retries on failure
    return {**order, "user": user}