Microservices Architecture Knowledge Base
Quick reference for microservices architecture patterns and PHP implementation guidelines.
Core Principles
Architecture Overview
┌──────────────────────────────────────────────────────────────────────────┐
│ MICROSERVICES ARCHITECTURE │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Client │────▶│ API Gateway │────▶│ Service A │ │
│ │ │ │ (Routing/Auth) │ │ (Own Database) │ │
│ └──────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │ │
│ │ │ async │
│ ┌──────▼──────┐ ┌─────▼──────────┐ │
│ │ Service B │ │ Message Broker │ │
│ │ (Own DB) │◀─────────│ (Events/Cmds) │ │
│ └─────────────┘ └────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ Decomposition Strategies: │
│ • By Business Capability - Align with bounded contexts │
│ • By Subdomain (DDD) - Core, Supporting, Generic │
│ • Strangler Fig - Incremental migration from monolith │
│ │
│ Communication: │
│ • Synchronous - REST, gRPC, GraphQL (request-response) │
│ • Asynchronous - Message queues, event streaming │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Service Communication Patterns
| Pattern | Type | Use When | Trade-off |
|---|
| REST | Sync | CRUD, simple queries | Easy but coupling |
| gRPC | Sync | Internal service-to-service, performance-critical | Fast but schema coupling |
| GraphQL | Sync | Client-driven queries, BFF | Flexible but complex |
| Message Queue | Async | Reliable delivery, work distribution | Decoupled but eventual consistency |
| Event Streaming | Async | Real-time, event sourcing, audit trails | Scalable but complex ordering |
| Request-Reply | Async | Async request needing response | Decoupled but higher latency |
API Gateway Patterns
| Pattern | Description | When to Use |
|---|
| Simple Proxy | Routes requests to services | Small number of services |
| Gateway Aggregation | Combines multiple service calls | Reduce client round-trips |
| BFF (Backend for Frontend) | Gateway per client type | Mobile vs Web vs API clients |
| Gateway Offloading | Auth, rate limiting, TLS | Cross-cutting concerns |
Service Discovery
| Approach | How It Works | Example |
|---|
| Client-side | Client queries registry, selects instance | Netflix Eureka |
| Server-side | Load balancer queries registry | AWS ALB, Kubernetes |
| DNS-based | DNS SRV records resolve to instances | Consul DNS, CoreDNS |
| Platform-native | Container orchestrator handles routing | Kubernetes Services |
Data Management
| Pattern | Description | Consistency |
|---|
| Database per Service | Each service owns its data | Strong (within service) |
| Shared Database | Services share one database | Strong (anti-pattern!) |
| Saga | Distributed transaction via events | Eventual |
| CQRS | Separate read/write models | Eventual |
| Event Sourcing | Events as source of truth | Eventual |
| API Composition | Query multiple services, merge results | Eventual |
When to Use Microservices vs Monolith
| Factor | Monolith | Microservices |
|---|
| Team size | < 10 developers | > 10, multiple teams |
| Domain complexity | Simple/moderate | Complex, many bounded contexts |
| Scalability needs | Uniform scaling | Independent scaling per component |
| Deployment frequency | Infrequent, coordinated | Frequent, independent |
| Technology diversity | Single stack | Polyglot needed |
| Organizational maturity | Starting out | DevOps culture, CI/CD mature |
Detection Patterns
# Service boundary indicators
Grep: "HttpClient|GuzzleHttp|curl_init" --glob "**/Infrastructure/**/*.php"
Grep: "grpc|protobuf" --glob "**/*.php"
# API Gateway patterns
Grep: "X-Forwarded|X-Request-ID|X-Correlation" --glob "**/*.php"
Glob: **/Gateway/**/*.php
# Service discovery
Grep: "ServiceDiscovery|ServiceRegistry|consul|etcd" --glob "**/*.php"
Grep: "KUBERNETES_SERVICE|SERVICE_HOST" --glob "**/*.env*"
# Database per service
Grep: "DATABASE_URL|DB_CONNECTION" --glob "**/*.env*"
Grep: "DATABASE_HOST|DB_HOST" --glob "**/docker-compose*.yml"
# Inter-service communication
Grep: "AMQPChannel|RabbitMQ|Kafka|SQS" --glob "**/Infrastructure/**/*.php"
Grep: "EventPublisher|MessageBus" --glob "**/*.php"
Advanced Patterns
Strangler Fig Pattern
Incrementally migrate from monolith to microservices:
Phase 1: Proxy all traffic through gateway
Phase 2: Extract one feature to service, route via gateway
Phase 3: Repeat until monolith is empty shell
Phase 4: Decommission monolith
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ Client │────▶│ Gateway │────▶│ New Service │ (extracted)
│ │ │ (Router) │ └──────────────┘
│ │ │ │────▶┌──────────────┐
│ │ │ │ │ Monolith │ (shrinking)
└─────────┘ └──────────┘ └──────────────┘
Migration Decision:
| Factor | Extract First | Keep in Monolith |
|---|
| Change frequency | High | Low |
| Team ownership | Dedicated team | Shared |
| Scaling needs | Independent scaling | Uniform |
| Technology fit | Different stack needed | Same stack fine |
API Gateway Aggregation Patterns
| Pattern | When | Example |
|---|
| Simple proxy | 1:1 route mapping | /users → User Service |
| Aggregation | Client needs data from N services | Order + Customer + Payment |
| BFF | Different clients need different data | Mobile vs Web vs API |
| Offloading | Cross-cutting concerns | Auth, rate limiting, TLS |
Database-Per-Service Trade-offs
| Aspect | Shared DB | DB per Service |
|---|
| Consistency | ACID transactions | Saga/eventual |
| Querying | JOIN across domains | API composition |
| Independence | Coupled deployments | Independent |
| Complexity | Low | High |
| Schema changes | Coordinated | Independent |
References
For detailed information, load these reference files:
references/patterns.md — Service mesh, API gateway implementations, service discovery details, data consistency, Strangler Fig, database-per-servicereferences/antipatterns.md — Distributed monolith, shared database, missing boundaries, chatty communication