| name | microservices |
| description | Microservices architecture patterns for PHP (Laravel/Symfony) and TypeScript (NestJS/Express) — service decomposition, DDD bounded contexts, sync/async communication, saga and event sourcing, resilience (circuit breaker, retry, bulkhead, timeout), observability (correlation IDs, distributed tracing, SLO), deployment (health probes, graceful shutdown), API gateway, and service mesh. Use when decomposing monoliths, designing new distributed systems, reviewing service boundaries, implementing inter-service communication, or hardening an existing microservice. |
| model | inherit |
Microservices
Distributed-system patterns for PHP and TypeScript services. Every rule file includes bad / good examples in both languages. Per-category guides live in references/.
When to Use
- Decomposing a monolith into independently deployable services
- Designing service boundaries, data ownership, and API contracts
- Choosing between synchronous (REST, gRPC) and asynchronous (Kafka, RabbitMQ, SQS) communication
- Implementing distributed transactions (saga), event sourcing, or CQRS
- Hardening resilience: circuit breakers, retries, timeouts, bulkheads, fallbacks
- Wiring observability: correlation IDs, distributed tracing, structured logs, SLI / SLO
- Setting up health probes, graceful shutdown, externalised config
- Designing API gateways or enrolling services into a service mesh (Istio, Linkerd)
Basic Coverage
Service ─── owns its own DB schema ─────────► no cross-service SQL / shared tables
◄── API contract (OpenAPI / proto) ── consumers depend on the contract, not the impl
Sync call ─── REST / gRPC with timeout ───────► circuit-breaker + retry(exp-backoff) + deadline
Async ─── publish DomainEvent to broker ──► subscribers react; producer never awaits
Saga ─── step + compensating action ─────► eventual consistency, idempotent steps
Request ─── X-Correlation-Id propagates ────► every log + span tagged with it
Pod ─── /health/live + /health/ready ───► k8s probes gate traffic and restarts
Deploy ─── config via env / secret ────────► rebuild image only for code changes
Core Directives
MUST DO
- One service owns one business capability (bounded context) — single responsibility
- Each service owns its own database schema — no cross-service reads or joins
- Every external call has an explicit
timeout, a bounded retry budget, and a fallback
- Every inbound request carries (or is assigned) a correlation ID that propagates to outbound calls, logs, and traces
- Health endpoints distinguish liveness (am I alive) from readiness (can I serve traffic)
- Consumers of async events are idempotent — deduplicate by
event_id or aggregate version
- Define API contracts first (OpenAPI, protobuf, AsyncAPI) — generate types / clients from them
- Externalise all config (env vars, secret manager) — the same artifact runs in every environment
- Ship structured logs (JSON) with
service, correlation_id, span_id, level
- Shutdown gracefully: stop accepting new work → drain in-flight → flush consumers → exit
MUST NOT DO
- Share a database schema between services
- Call another service without a timeout (defaults are almost always too high)
- Use distributed two-phase commit / XA across services — use sagas
- Retry non-idempotent POSTs without an
Idempotency-Key
- Emit domain events whose shape depends on internal DB columns — events are a public contract
- Log secrets, tokens, JWTs, or full request bodies — redact first
- Couple services to each other's deployment cadence (synchronous deploy dependencies)
- Put business logic in the API gateway — it routes, auths, and rate-limits, nothing more
Specialized Agents
Specialized personas for microservices architecture. Load these from agents/ to provide expert context.
| Agent | Role | Focus |
|---|
| microservices-pro | Architecture Expert | Service boundaries, Saga/CQRS, resilience, observability. |
Category Index — When to Load Which Reference
| # | Category | Impact | Load when… | Reference | Prefix | Rules |
|---|
| 1 | Service Boundaries & Decomposition | CRITICAL | Splitting a monolith, drawing service boundaries, deciding data ownership | references/boundaries.md | boundary- | 4 |
| 2 | Inter-Service Communication | CRITICAL | Choosing sync vs async, REST / gRPC / Kafka / RabbitMQ, contracts | references/communication.md | comm- | 5 |
| 3 | Data Management | CRITICAL | Saga vs 2PC, event sourcing, CQRS, eventual consistency | references/data.md | data- | 4 |
| 4 | Resilience | CRITICAL | Adding circuit breakers, retries, bulkheads, timeouts, fallbacks | references/resilience.md | resil- | 5 |
| 5 | Observability | HIGH | Correlation IDs, tracing, structured logs, SLI / SLO | references/observability.md | obs- | 4 |
| 6 | Deployment & Operations | HIGH | Health probes, graceful shutdown, config, zero-downtime rollouts | references/operations.md | ops- | 4 |
| 7 | API Gateway & Service Mesh | HIGH | BFF / gateway design, mTLS, traffic splitting, mesh policies | references/gateway-mesh.md | gw- | 3 |
Load only the reference(s) relevant to the current task — not all seven.
Rule Index — Direct Jumps
Each rules/<name>.md has: frontmatter (title, impact, tags), rationale, bad example (PHP + TS), good example (PHP + TS).
1. Boundaries (boundary-) — CRITICAL
boundary-ddd-bounded-contexts · boundary-database-per-service · boundary-single-responsibility · boundary-strangler-fig
2. Communication (comm-) — CRITICAL
comm-sync-rest-grpc · comm-async-messaging · comm-pubsub-events · comm-idempotent-consumers · comm-api-contracts
3. Data (data-) — CRITICAL
data-saga-orchestration · data-saga-choreography · data-event-sourcing · data-cqrs
4. Resilience (resil-) — CRITICAL
resil-circuit-breaker · resil-retry-backoff · resil-timeouts · resil-bulkhead · resil-graceful-degradation
5. Observability (obs-) — HIGH
obs-correlation-ids · obs-distributed-tracing · obs-structured-logging · obs-slo-sli
6. Operations (ops-) — HIGH
ops-health-probes · ops-graceful-shutdown · ops-config-externalization · ops-zero-downtime-deploys
7. Gateway & Mesh (gw-) — HIGH
gw-api-gateway · gw-service-mesh-mtls · gw-rate-limiting
Target Stacks
| Concern | PHP suggestion | TypeScript suggestion |
|---|
| HTTP framework | Laravel 13, Symfony 7, Slim 4 | NestJS 10, Fastify, Express 4 |
| Async broker | Laravel queues (Redis/SQS), Symfony Messenger, php-amqplib | @nestjs/microservices, kafkajs, amqplib, bullmq |
| RPC | spiral/roadrunner-grpc, google/protobuf | @grpc/grpc-js, ts-proto |
| Circuit breaker | ackintosh/ganesha | opossum, cockatiel |
| Tracing | OpenTelemetry PHP SDK | @opentelemetry/sdk-node |
| Service mesh | Istio / Linkerd (language-agnostic) | Istio / Linkerd |
| Orchestrator | Kubernetes | Kubernetes |
Validation Checklist (Architecture Review)
Use this before calling an architecture "done":
External References
