Microservices Architecture
Purpose
Make several individually plausible decisions work together for one business outcome. Own their dependencies, conflicting assumptions and integration evidence. A list of patterns or services is insufficient: show which decision constrains which other decision, who can resolve a conflict, and what the next useful increment will prove.
Use this after the affected initiative or use case is known. Initial enterprise orientation
belongs to enterprise-application-architecture; distributed symptom triage belongs to
distributed-systems. A single timeout adjustment belongs to timeouts-and-deadlines.
Do not send these tasks through the entire architecture track. Whether a particular module
should become a process belongs to distribution-boundaries; carry its decision forward
rather than redoing its analysis here.
Establish the working constraints
Start from the requested result: review findings, an architecture decision, or implemented changes. Reuse accepted decisions and existing evidence. Keep a suitable monolith or existing service arrangement when it meets the outcome; neither a service count nor a bounded-context count is a success criterion. Reopen an accepted boundary only when a changed requirement or contradictory evidence warrants it.
Trace one representative business operation before mapping the whole system:
- Outcome and invariants: caller, protected business effect, latency/availability or
freshness requirement, prohibited intermediate states, and the party authorized to
change those requirements. Separate binding constraints from preferences such as
"every capability needs a service." Use
architecture-characteristicswhen the outcome is still only "scalable" or "reliable." - Actual path: entry points, domain rules, transaction/data owners, calls/events, consumers, scheduled jobs, credentials and trust boundaries. Compare source/contracts with deployments and observations; a diagram or annotation is an assertion to check.
- Delivery and operation: current compatibility promises, release history, incidents, support ownership, deployment units, failure domains and existing recovery procedures. Use changes and incident evidence to test autonomy or isolation claims; separate pipelines alone establish neither.
- Java/Spring target when present: Maven/Gradle toolchains, compiler release, resolved dependency management, Spring Boot/Framework/Cloud versions, runtime images and CI. Inspect transaction managers, client configuration and effective profiles for the affected path. This skill has no fixed Java baseline or executable example and grants no upgrade, preview-feature or new-platform requirement.
Distinguish observed facts, inferred relationships and untested hypotheses. Record the artifact/version and relevant workload or capture window behind consequential evidence. If evidence is absent, name the smallest missing trace, contract or owner answer; continue independent work and keep dependent conclusions conditional. Do not invent owners, traffic volumes or performance gains to complete a map.
Build and reconcile the decision map
Keep the map in the project's existing architecture record or task artifact. Link existing ADRs rather than copying them. For each consequential open or affected decision, record:
- Question and constraint: affected operation/invariant, evidence and any assumption that could change the answer.
- Choice and alternative: retain/change/probe, rationale, consequential cost and what
would cause reconsideration. When option comparison needs depth, use
architecture-trade-off-analysis. - Accountability: decision authority, implementation/operation owner and specialist question. An advisory skill is not the accountable team.
- Dependencies and status: decisions this answer needs or constrains, conflicting requirement/assumption, and whether the choice is proposed or accepted. Track its validation separately: accepted does not mean demonstrated.
- Acceptance evidence: observable result, check/fixture, responsible owner and any
remaining limit. Use
architecture-decision-makingfor ADR lifecycle, proportionate to the consequence.
Order work by actual dependencies and uncertainty. Settle a blocking invariant or authority question before committing its dependent API/read model. Independent investigations can proceed together; a circular dependency is a reason for a bounded joint experiment or requirement clarification, not an arbitrary ordering. Send each specialist the existing evidence and exact unresolved question, and require a returned contract, assumptions, failure semantics and verification. Do not restart discovery at each handoff.
When an answer changes, revisit only its dependent decisions. Compare their assumptions at the shared boundary: identity/tenant, authoritative state, allowed staleness, transaction participation, deadline, failure outcome and supported versions. For example, an available cached balance does not establish permission to spend it, and moving work behind a gateway does not establish authorization at the operation. Route the unresolved mechanism instead of filling the gap with a framework annotation.
Reconcile time and load across the whole call path too: separately accepted timeout/retry policies can exhaust the caller's budget or multiply downstream attempts. Inspect effective gateway, client and SDK policies before accepting a composed guarantee. The integration reference identifies the evidence to pass to the timeout/retry specialists.
If two binding constraints cannot both hold under the proposed design, expose the conflict and the options to its decision authority. Do not silently weaken an invariant or label an unapproved compromise accepted. Read Integrating decisions when proposals conflict, a process boundary changes semantics, or an implementation slice needs checks across several owners.
Ask the specialist for a bounded result
Load only owners needed by the current questions. This table states the handoff contract; the detailed mechanism remains in its owning skill.
| Unresolved question | Owner | Result to integrate |
|---|---|---|
| Which meanings and invariants belong together? | bounded-context-design |
Context relationships and translation contracts, without assuming a process per context. |
| Who may read or mutate authoritative data? | service-data-ownership |
Supported interfaces, enforceable access rules and bounded exceptions. |
| How does a cross-service read meet its consumer's semantics? | cross-service-query-design |
Freshness/completeness/authorization contract and recovery of derived state. |
| What belongs at the client-facing edge? | api-gateway-and-bff |
Edge responsibilities, identity propagation and partial-failure behavior. |
| How does a caller learn changing endpoints? | service-discovery |
Bootstrap/update/expiry behavior, including stale or absent discovery data. |
| Which workload or delegated identity is trusted for this operation? | service-identity-and-trust |
Trust and authorization boundaries, rotation and denial behavior. |
| How can versions coexist and an unsafe release be stopped? | progressive-service-delivery |
Compatibility constraints, cohorts, promotion/abort evidence and data-aware recovery. |
Use these specialists for the remaining affected contracts and their verification:
rpc-and-api-contractsandschema-evolution-and-compatibilityfor wire behavior and version coexistence;distributed-transactions-and-sagasandidempotencyfor cross-owner effects, delivery gaps, uncertain outcomes and safe repetition.distributed-systems-testingfor failure evidence andslo-and-alertingfor operational acceptance. Reuse established evidence when it covers the proposed change.
For deeper analysis or framework-specific work, consult:
architecture-coupling-and-quantawhen the independence claim needs a deeper coupling assessment;architecture-refactoring-pathswhen a migration across boundaries needs sequencing beyond the first slice.spring-bootfor applicable Spring implementation routing, carrying the discovered project baseline. Consultspring-transactions-and-eventswhen transaction or publication behavior is material, andspring-boot-testingfor integration verification.
If an owner is unavailable, retain the question and next discriminating check in the map; do not claim its work happened or install tools/skills as a prerequisite without need.
Deliver the first verifiable slice
Choose the smallest business operation that tests the highest-risk interaction among the decisions. State the effect and consumer, included paths, excluded work and why the result will change confidence in the architecture. A small internal modular change can be the right slice. A disconnected service scaffold cannot demonstrate an integration claim.
For a review, deliver the evidenced conflicts or supported retained decisions and their consequences. For a design, deliver the reconciled map and an executable next validation step. For an implementation request, continue through the authorized slice: domain/API change, affected callers or consumers, configuration, data/permission changes, operational documentation and recovery where relevant. Reuse project conventions and supported dependencies; preserve encapsulation and business types, and justify new shared libraries or abstractions by actual consumers. Do not stop after naming specialists.
Verify the combined path with checks capable of refuting its claims: business effect and invariant, realistic dependency failure, relevant unauthorized access, and mixed versions when coexistence is promised. Match deployment/capacity claims to the target topology and workload; mock-only checks cannot demonstrate those properties. For a local-only change, do not manufacture distributed failure tests. Choose checks from the actual map.
Return the retained/changed decisions, unresolved conflicts with owners, slice artifacts or implementation, commands/cases and observed results, plus the next decision affected by that evidence. Separate structural checks, executed behavior and unexecuted plans; state tool/environment limits. An integrated test in an isolated environment is evidence for its exercised conditions, not proof of production autonomy, security or availability.
Sources and limits
- Lewis and Fowler, Microservices: consult when interpreting independent deployment, business capabilities and failure costs. These are architectural observations, not a conformance checklist.
- Fowler, Monolith First: consult when evaluating an assumed extraction trajectory. Its tentative experiential argument supports considering retention, not a universal rule against starting with services.