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
1---2name: microservices-knowledge3description: Microservices Architecture knowledge base. Provides service decomposition, communication patterns, API gateway, service discovery, and data management guidelines for architecture audits and generation.4---56# Microservices Architecture Knowledge Base78Quick reference for microservices architecture patterns and PHP implementation guidelines.910## Core Principles1112### Architecture Overview1314```15┌──────────────────────────────────────────────────────────────────────────┐16│ MICROSERVICES ARCHITECTURE │17├──────────────────────────────────────────────────────────────────────────┤18│ │19│ ┌──────────┐ ┌──────────────────┐ ┌──────────────────┐ │20│ │ Client │────▶│ API Gateway │────▶│ Service A │ │21│ │ │ │ (Routing/Auth) │ │ (Own Database) │ │22│ └──────────┘ └──────────────────┘ └──────────────────┘ │23│ │ │ │24│ │ │ async │25│ ┌──────▼──────┐ ┌─────▼──────────┐ │26│ │ Service B │ │ Message Broker │ │27│ │ (Own DB) │◀─────────│ (Events/Cmds) │ │28│ └─────────────┘ └────────────────┘ │29│ │30├──────────────────────────────────────────────────────────────────────────┤31│ │32│ Decomposition Strategies: │33│ • By Business Capability - Align with bounded contexts │34│ • By Subdomain (DDD) - Core, Supporting, Generic │35│ • Strangler Fig - Incremental migration from monolith │36│ │37│ Communication: │38│ • Synchronous - REST, gRPC, GraphQL (request-response) │39│ • Asynchronous - Message queues, event streaming │40│ │41└──────────────────────────────────────────────────────────────────────────┘42```4344## Service Communication Patterns4546| Pattern | Type | Use When | Trade-off |47|---------|------|----------|-----------|48| REST | Sync | CRUD, simple queries | Easy but coupling |49| gRPC | Sync | Internal service-to-service, performance-critical | Fast but schema coupling |50| GraphQL | Sync | Client-driven queries, BFF | Flexible but complex |51| Message Queue | Async | Reliable delivery, work distribution | Decoupled but eventual consistency |52| Event Streaming | Async | Real-time, event sourcing, audit trails | Scalable but complex ordering |53| Request-Reply | Async | Async request needing response | Decoupled but higher latency |5455## API Gateway Patterns5657| Pattern | Description | When to Use |58|---------|-------------|-------------|59| Simple Proxy | Routes requests to services | Small number of services |60| Gateway Aggregation | Combines multiple service calls | Reduce client round-trips |61| BFF (Backend for Frontend) | Gateway per client type | Mobile vs Web vs API clients |62| Gateway Offloading | Auth, rate limiting, TLS | Cross-cutting concerns |6364## Service Discovery6566| Approach | How It Works | Example |67|----------|-------------|---------|68| Client-side | Client queries registry, selects instance | Netflix Eureka |69| Server-side | Load balancer queries registry | AWS ALB, Kubernetes |70| DNS-based | DNS SRV records resolve to instances | Consul DNS, CoreDNS |71| Platform-native | Container orchestrator handles routing | Kubernetes Services |7273## Data Management7475| Pattern | Description | Consistency |76|---------|-------------|-------------|77| Database per Service | Each service owns its data | Strong (within service) |78| Shared Database | Services share one database | Strong (anti-pattern!) |79| Saga | Distributed transaction via events | Eventual |80| CQRS | Separate read/write models | Eventual |81| Event Sourcing | Events as source of truth | Eventual |82| API Composition | Query multiple services, merge results | Eventual |8384## When to Use Microservices vs Monolith8586| Factor | Monolith | Microservices |87|--------|----------|---------------|88| Team size | < 10 developers | > 10, multiple teams |89| Domain complexity | Simple/moderate | Complex, many bounded contexts |90| Scalability needs | Uniform scaling | Independent scaling per component |91| Deployment frequency | Infrequent, coordinated | Frequent, independent |92| Technology diversity | Single stack | Polyglot needed |93| Organizational maturity | Starting out | DevOps culture, CI/CD mature |9495## Detection Patterns9697```bash98# Service boundary indicators99Grep: "HttpClient|GuzzleHttp|curl_init" --glob "**/Infrastructure/**/*.php"100Grep: "grpc|protobuf" --glob "**/*.php"101102# API Gateway patterns103Grep: "X-Forwarded|X-Request-ID|X-Correlation" --glob "**/*.php"104Glob: **/Gateway/**/*.php105106# Service discovery107Grep: "ServiceDiscovery|ServiceRegistry|consul|etcd" --glob "**/*.php"108Grep: "KUBERNETES_SERVICE|SERVICE_HOST" --glob "**/*.env*"109110# Database per service111Grep: "DATABASE_URL|DB_CONNECTION" --glob "**/*.env*"112Grep: "DATABASE_HOST|DB_HOST" --glob "**/docker-compose*.yml"113114# Inter-service communication115Grep: "AMQPChannel|RabbitMQ|Kafka|SQS" --glob "**/Infrastructure/**/*.php"116Grep: "EventPublisher|MessageBus" --glob "**/*.php"117```118119## Advanced Patterns120121### Strangler Fig Pattern122123Incrementally migrate from monolith to microservices:124125```126Phase 1: Proxy all traffic through gateway127Phase 2: Extract one feature to service, route via gateway128Phase 3: Repeat until monolith is empty shell129Phase 4: Decommission monolith130131┌─────────┐ ┌──────────┐ ┌──────────────┐132│ Client │────▶│ Gateway │────▶│ New Service │ (extracted)133│ │ │ (Router) │ └──────────────┘134│ │ │ │────▶┌──────────────┐135│ │ │ │ │ Monolith │ (shrinking)136└─────────┘ └──────────┘ └──────────────┘137```138139**Migration Decision:**140141| Factor | Extract First | Keep in Monolith |142|--------|--------------|------------------|143| Change frequency | High | Low |144| Team ownership | Dedicated team | Shared |145| Scaling needs | Independent scaling | Uniform |146| Technology fit | Different stack needed | Same stack fine |147148### API Gateway Aggregation Patterns149150| Pattern | When | Example |151|---------|------|---------|152| Simple proxy | 1:1 route mapping | `/users` → User Service |153| Aggregation | Client needs data from N services | Order + Customer + Payment |154| BFF | Different clients need different data | Mobile vs Web vs API |155| Offloading | Cross-cutting concerns | Auth, rate limiting, TLS |156157### Database-Per-Service Trade-offs158159| Aspect | Shared DB | DB per Service |160|--------|-----------|----------------|161| Consistency | ACID transactions | Saga/eventual |162| Querying | JOIN across domains | API composition |163| Independence | Coupled deployments | Independent |164| Complexity | Low | High |165| Schema changes | Coordinated | Independent |166167## References168169For detailed information, load these reference files:170171- `references/patterns.md` — Service mesh, API gateway implementations, service discovery details, data consistency, Strangler Fig, database-per-service172- `references/antipatterns.md` — Distributed monolith, shared database, missing boundaries, chatty communication
dykyi-roman