| 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.
