microservice-architect

name	microservice-architect
description	Guides the planning of a microservices architecture. Use this skill when asked to design, plan, or architect a system using microservices. This skill helps with service boundary identification, communication pattern selection, data management, and defining service contracts.

Microservice Architect

Overview

This skill provides a structured workflow for planning a microservices architecture. It helps in making key architectural decisions and producing standard deliverables.

The process is divided into four main steps. Follow them in order to ensure a comprehensive design.

Step 1: Decompose the System into Services

The first step is to identify the boundaries of each microservice. The goal is to create services that are loosely coupled and highly cohesive.

• Action: Use the service decomposition template to document each proposed service.
• Template: assets/templates/service_decomposition_template.md
• Guidelines: Refer to references/service_decomposition.md for criteria on how to define service boundaries, based on principles like Domain-Driven Design.

For each potential service, copy the template and fill it out.

Step 2: Define Communication Patterns

Once services are identified, determine how they will communicate with each other.

• Action: For each interaction between services, choose a suitable communication pattern.
• Decision Matrix: Use the matrix in assets/templates/communication_matrix_template.md to help select between REST, gRPC, GraphQL, and messaging.
• Reference: For more details on each pattern, see references/communication_patterns.md.

Not all services need to use the same pattern. Choose the best fit for each interaction.

Step 3: Plan Data Management and Infrastructure

Address how data will be managed across services and what infrastructure is needed.

• Data Ownership: Follow the database-per-service pattern. See references/data_patterns.md for details on this and handling distributed transactions with the Saga pattern.
• Infrastructure: Plan for service discovery and an API gateway. Guidance can be found in references/infrastructure.md.
• Event-Driven: If asynchronous communication is used, review patterns for event-driven architecture in references/event_driven.md.

Step 4: Create Architecture Diagrams and Service Contracts

The final step is to document the architecture and the service APIs.

• Architecture Diagrams: Use the C4 model to visualize the architecture. Create System Context and Container diagrams at a minimum. See references/c4_model.md for an explanation of the C4 model.
• Service Contracts: For each service, create a formal API contract.
  • Template: A basic OpenAPI template is available at assets/templates/service_contract_template.json.
  • Guidelines: See references/service_contracts.md for details on what to include in a contract and different specification formats.

Deliverables

By the end of this process, you will have produced:

• A set of completed service decomposition documents.
• A communication matrix for service interactions.
• C4 model architecture diagrams.
• Service interface contracts for each service.