skills/software-architecture-design/assets/patterns/microservices-template.md

Microservices Architecture Template

Use this template when designing a microservices-based system.

Service Definition

• Service name: [ServiceName]
• Bounded context: [Domain boundary this service owns]
• Team owner: [Team responsible for this service]

Service Responsibilities

• Core capabilities:
  • [Primary business capability 1]
  • [Primary business capability 2]
• Data ownership:
  • [Entities this service owns]
  • [Events this service publishes]

API Contract

REST Endpoints

GET    /api/v1/[resource]
POST   /api/v1/[resource]
PUT    /api/v1/[resource]/{id}
DELETE /api/v1/[resource]/{id}

Events Published

• [EventName]: Published when [trigger condition]
• [EventName]: Published when [trigger condition]

Events Consumed

• [EventName]: From [SourceService], triggers [action]

Dependencies

Upstream Services (Calls)

• [ServiceName]: For [purpose], timeout: [Xms], circuit breaker threshold: [N failures]

Downstream Services (Called by)

• [ServiceName]: Expects [SLA], provides [data/functionality]

Data Storage

• Database type: [PostgreSQL / MongoDB / Cassandra / etc.]
• Schema approach: [Database-per-service / Shared tables / etc.]
• Replication: [Primary-replica / Multi-master]
• Backup strategy: [Automated daily / Point-in-time recovery]

Resilience

• Timeouts:
  • Database queries: [Xms]
  • External API calls: [Xms]
  • Internal service calls: [Xms]
• Retry policy: Exponential backoff, max [N] retries
• Circuit breaker: Open after [N] failures, half-open after [X] seconds
• Rate limiting: [N] requests per second per client
• Fallback behavior: [Return cached data / Default response / Graceful degradation]

Observability

• Metrics:
  • Request rate, latency (p50, p95, p99)
  • Error rate (4xx, 5xx)
  • Dependency health
  • Business metrics: [specific to service]
• Distributed tracing: Jaeger/OpenTelemetry with trace IDs
• Logging:
  • Structured JSON logs
  • Log level: INFO in production, DEBUG in dev
  • Key fields: trace_id, user_id, service_name, timestamp
• Health checks:
  • Liveness: /health/live (basic ping)
  • Readiness: /health/ready (dependencies check)

Deployment

• Container: Docker image, registry: [ECR / Docker Hub / etc.]
• Orchestration: Kubernetes
• Scaling policy:
  • Min replicas: [N]
  • Max replicas: [N]
  • Scale trigger: CPU > [X]% or Memory > [X]% or RPS > [N]
• Deployment strategy: Rolling update / Canary / Blue-green
• Rollback plan: Automated rollback if error rate > [X]%

Security

• Authentication: JWT tokens, validated via [Auth service / API Gateway]
• Authorization: Role-based access control (RBAC)
• Service-to-service auth: mTLS via service mesh
• Secrets: Stored in [AWS Secrets Manager / Vault / Kubernetes Secrets]
• Input validation: All user inputs validated and sanitized
• Rate limiting: Per-user and per-IP limits

Testing

• Unit tests: Coverage target: 80%+
• Integration tests: Test API contracts and database interactions
• Contract tests: Pact/Spring Cloud Contract for upstream/downstream
• Load tests: Target [N] RPS at p95 < [Xms]
• Chaos testing: Simulate dependency failures, network latency

Communication Patterns

• Synchronous: REST/gRPC for request-response
• Asynchronous: Kafka/RabbitMQ for events
• Idempotency: All write operations support idempotency keys
• Message format: JSON for REST, Protobuf for gRPC, Avro for Kafka

Cost Optimization

• Resource allocation:
  • CPU request: [Xm], limit: [Xm]
  • Memory request: [XMi], limit: [XMi]
• Auto-scaling: Scale down during off-peak hours
• Data retention: [X days] for logs, [X days] for metrics

Migration Plan

• Phase 1: [Extract service from monolith / Build new service]
• Phase 2: [Gradual traffic migration / Feature flag rollout]
• Phase 3: [Full cutover / Decommission old system]
• Rollback criteria: [Error rate / Latency / Business metrics]

ADR References

• [ADR-001]: [Decision about technology choice]
• [ADR-002]: [Decision about data model]