Microservice Researcher

Microservice Researcher

When to Use

• Research domain decomposition, bounded contexts, and candidate service boundaries
• Compare microservices vs modular monolith (or other styles) with explicit trade-offs
• Analyze sync vs async integration, data ownership, and consistency models at decision level
• Evaluate saga vs 2PC, outbox, and choreography/orchestration without implementation tutorials
• Define API and contract evolution strategy (versioning, compatibility, deprecation)
• Plan monolith-to-microservices migration (strangler, parallel run, cutover criteria)
• Align services with Team Topologies (stream-aligned, platform, enabling, complicated-subsystem)
• Assess build vs buy vs managed for cross-cutting capabilities
• Quantify NFR impact (latency budgets, reliability, operability, cost) per boundary option
• Produce ADRs, options matrices, and research memos with a clear recommendation

When NOT to Use

• Write or refactor production microservice code, handlers, or deployables → senior-software-engineer
• Operate Kubernetes clusters, Terraform modules, or CI/CD pipelines only → platform-engineer, cloud-engineer, infrastructure-engineer
• Design carrier/WAN routing, VPC topology, or physical network without application boundaries → network-backbone-architect
• Implement brokers, outbox consumers, schema registry ops, or stream processing → event-driven-architecture (when building), microservices-developer
• Enterprise portfolio strategy, operating model, and board-level where-to-play → enterprise-strategist
• Load-test execution, caching implementation, and horizontal scale tuning only → high-concurrency-scalability
• Cross-domain system architecture sign-off unrelated to service decomposition → senior-system-architecture (hand off when scope is whole-estate ADR)
• Inventory, dependency maps, SLO gaps, API drift, or operational health on a live estate → microservices-analyst

Related skills

Core Workflows

1. Frame the research question

Capture before comparing boundaries:

• Business capability and measurable outcome
• Constraints: teams, timeline, compliance, existing monolith/estate
• Reversibility (one-way vs two-way door)
• Non-goals and explicit out-of-scope peers

See `references/microservice_researcher_scope.md`.

2. Decompose the domain

Identify bounded contexts, ubiquitous language, and context maps (upstream/downstream, ACL, OHS).

Produce candidate services with ownership hypotheses—not a box diagram without data flow.

See `references/domain_decomposition_and_boundaries.md`.

3. Integration and consistency

For each boundary, document sync/async choice, data ownership, consistency model, and failure semantics.

Compare eventual consistency, saga compensation, and 2PC only when research warrants—not as default distributed transactions.

See `references/integration_patterns_and_consistency.md`.

4. Contracts and evolution

Define public API/event contracts, versioning rules, compatibility matrix, and deprecation timeline.

See `references/api_contracts_and_evolution.md`.

5. Migration and organization

Plan strangler slices, parity criteria, dual-write/read duration, and team alignment (Team Topologies).

See `references/migration_strangler_and_org_alignment.md`.

6. Deliverables and decision record

Package options matrix, NFR table, risks, recommendation, and follow-on owners (build vs research complete).

See `references/research_deliverables_and_decision_records.md`.

Principles

• Research before split—boundaries follow domain and team cognition, not org chart alone
• Prefer reversible experiments—strangler slices over big-bang when uncertainty is high
• One writer per aggregate—document who owns each consistency boundary
• Make trade-offs explicit—latency, ops burden, and team autonomy in the same table
• Cite patterns and literature—DDD, Team Topologies, enterprise integration patterns—without cargo-culting microservices

API contracts and evolution

Table of contents

1. Contract types 2. Design-first research outputs 3. Versioning strategies 4. Compatibility matrix 5. Deprecation and sunset 6. Governance 7. Research checklist

Contract types

Align public contracts with bounded context boundaries—no "god API" without explicit aggregation role (BFF).

Design-first research outputs

Before implementation commitment:

• Consumer list — internal, partner, mobile, analytics
• SLA class — best-effort vs critical path
• Error taxonomy — retryable vs fatal; problem+json or gRPC status mapping
• Pagination and filtering — cursor vs offset; max page size
• AuthZ model — scopes, claims, service-to-service identity

Produce contract sketch (OpenAPI/AsyncAPI fragment) for review—not full implementation.

Versioning strategies

Compare options in ADR:

Research recommendation: pick one primary strategy per surface area; document exceptions.

Breaking vs non-breaking changes

Compatibility matrix

Define for APIs and events:

Consumer-driven contracts: research should recommend who runs pact/schema tests and on which cadence.

Deprecation and sunset

Policy elements:

1. Announcement — changelog, portal, email to registered consumers 2. Dual support window — minimum duration (e.g., 6–12 months for partners) 3. Telemetry gate — zero traffic on old version before removal 4. Forced migration — only with executive risk acceptance

Document sunset criteria in research memo—not "deprecate when convenient."

Governance

Hand off enterprise-wide API programs to enterprise-integration-api-developer.

Research checklist

• [ ] Public vs internal contract surfaces separated
• [ ] Versioning strategy chosen with examples
• [ ] Compatibility rules stated (backward/forward)
• [ ] Deprecation timeline template attached
• [ ] Error and idempotency conventions referenced
• [ ] Event schemas linked if async boundary exists
• [ ] NFR: rate limits, payload size, timeout documented

Domain decomposition and boundaries

Table of contents

1. Discovery inputs 2. Bounded context heuristics 3. Context mapping 4. Service boundary criteria 5. Granularity trade-offs 6. Research checklist

Discovery inputs

Gather before drawing services:

Time-box discovery; record assumptions when stakeholders are unavailable.

Bounded context heuristics

A bounded context has:

• Ubiquitous language stable within the boundary
• Models that need not match other contexts (e.g., Customer in Sales vs Support)
• Autonomous evolution of rules without negotiating every change globally

Signals of a separate context:

• Different lifecycle or definition of core entities
• Different scaling or availability targets
• Regulatory or trust-zone separation
• Team can own outcomes without daily sync to another team

Signals to keep together:

• Same aggregate enforces invariants across entities
• Frequent invariant changes span proposed split
• Read-your-writes required on a single user action with no acceptable lag

Context mapping

Document relationships between contexts (DDD context map):

Output: diagram + table of who translates what at each edge.

Service boundary criteria

Score each candidate service (1–5) against weighted criteria:

Split when high cohesion + clear data ownership + deploy independence outweigh ops overhead.

Merge when low cohesion or consistency forces distributed transactions.

Granularity trade-offs

Nano-services warning: research should flag services with <1 meaningful aggregate or no independent lifecycle.

Modular monolith option: always include as Option A in comparisons when estate is single-team or maturity is low.

Research checklist

• [ ] Ubiquitous language glossary per context
• [ ] Aggregates identified with single-writer rule
• [ ] Context map with integration pattern per edge
• [ ] Hot paths counted (sync call depth, fan-out)
• [ ] Shared database tables flagged with migration owner
• [ ] At least two boundary options (including fewer services)
• [ ] Team Topologies hypothesis documented (see migration_strangler_and_org_alignment.md)

Integration patterns and consistency

Table of contents

1. Pattern selection 2. Sync integration research 3. Async and events research 4. Consistency models 5. Distributed workflows at research level 6. Failure and UX semantics 7. Anti-patterns

Pattern selection

Document per journey which pattern applies; avoid global "we are event-driven" without exceptions.

Sync integration research

For REST/GraphQL/gRPC boundaries, research should specify:

• Timeout budget vs caller SLO (cascade failure analysis)
• Idempotency for retried mutations (keys, dedup store)
• Versioning and deprecation (see api_contracts_and_evolution.md)
• Auth model — mTLS, OAuth scopes, service identity
• Circuit breaking policy when dependency error rate spikes

Choreography risk: deep sync chains (A→B→C→D) on user path—research should quantify p99 latency sum and failure modes.

Async and events research

At research level, define—not implement:

Outbox/inbox: recommend when business write and publish must not diverge; note operational cost.

Consistency models

Research rule: state maximum acceptable staleness on read models (e.g., "catalog search ≤ 30s behind writes").

Saga vs two-phase commit (2PC)

Default research stance: prefer saga with compensating actions over 2PC across microservices; document compensation UX (what user sees on partial failure).

Do not specify framework code—reference event-driven-architecture for saga/outbox implementation patterns.

Distributed workflows at research level

For each multi-step business process, deliver:

1. Steps — services involved, sync vs async per step 2. Compensations — reversible actions or manual intervention 3. Terminal states — success, failed, pending, needs-ops 4. Idempotency keys — per step correlation 5. Observability — correlation ID across boundaries

Failure and UX semantics

Research must answer for partial failure:

• Can user retry safely?
• Is state visible (pending payment, order processing)?
• Who reconciles orphaned events (ops playbook outline)?

Anti-patterns

• Distributed monolith — independent deploy labels but shared DB and library coupling
• Events without schema policy — implicit JSON contracts
• Sync mesh — N×M point-to-point without gateway or events
• 2PC by default — locks across services for convenience
• Saga without compensation design — "rollback" undefined for human steps

Microservice researcher scope

Table of contents

1. Role focus 2. Research vs delivery 3. Typical deliverables 4. Decision boundaries 5. Anti-patterns

Role focus

Research vs delivery

Stop research when: decision owner accepts recommendation, constraints are stable, and implementation backlog is owned by engineering—with explicit open questions logged.

Typical deliverables

• Research brief — question, constraints, method, sources, recommendation
• Context map — bounded contexts, relationships (customer/supplier, ACL, OHS, shared kernel risks)
• Candidate service catalog — name, owner team hypothesis, data owned, APIs/events published
• Integration/consistency note — per flow: sync/async, consistency, idempotency, failure UX
• Contract evolution policy — versioning, compatibility, sunset rules
• Migration roadmap — strangler slices, parity checklist, telemetry gates
• ADR — options, criteria weights, decision, consequences (see references/research_deliverables_and_decision_records.md)

Decision boundaries

Favor microservices (or finer boundaries) when research shows:

• Independent release cadence per capability with acceptable contract discipline
• Teams can own data end-to-end without constant cross-team transactions
• NFRs differ materially (scale, availability, compliance zone) per capability
• Organizational alignment supports stream-aligned ownership

Favor modular monolith or fewer services when research shows:

• Domain is still volatile—boundaries would churn monthly
• Consistency needs dominate user journeys (strong consistency on critical path)
• Operational maturity cannot absorb distributed failure modes yet
• Team size cannot support on-call per service

Default stance: microservices are a means (autonomy, scale, isolation)—not an end state. Document why split beats a well-modularized monolith.

Anti-patterns

• Org-chart services — one service per manager without domain cohesion
• Research without owners — options matrix with no decision maker or date
• Distributed monolith research — many boxes, shared database, coupled deploys labeled "microservices"
• Skipping NFR column — boundary choice without latency, ops, or cost estimate
• Implementation smuggled into research — framework and broker selection before boundary agreement
• Infinite discovery — no time-box; recommend "decide and revisit" when evidence plateaus

Migration, strangler, and org alignment

Table of contents

1. Migration drivers 2. Strangler fig pattern 3. Slice definition 4. Data migration research 5. Cutover and parity 6. Team Topologies alignment 7. Build vs buy vs managed 8. Anti-patterns

Migration drivers

Document why leave monolith (or coarser estate):

Include cost of migration (dual-run, training, ops) in options matrix.

Strangler fig pattern

Concept: incrementally route traffic from legacy to new implementation behind a facade (gateway, router, feature flags) until legacy can be retired.

Research outputs:

1. Facade placement — edge gateway, monolith module router, or sidecar 2. Routing rules — by tenant, feature flag, % canary, or URL path 3. Telemetry — compare latency/error between legacy and new paths 4. Retirement gate — zero traffic + parity checklist green

Not big-bang unless constraints force it—document risk explicitly.

Slice definition

A viable strangler slice:

• Delivers user-visible or measurable value when extracted
• Owns data it writes (with migration plan for reads)
• Minimizes dual-write duration
• Has clear rollback (route traffic back)

Order slices by learning and risk, not by "easiest code."

Data migration research

For each slice, specify:

Hand off detailed pipeline design to data-architect when warehouse/CDC scope dominates.

Cutover and parity

Parity checklist (before traffic shift):

• Functional equivalence on critical journeys
• Performance within agreed % of legacy
• Security — authZ parity, audit logs
• Observability — dashboards/alerts for new path
• Support runbook outline

Cutover types:

Coordinate execution runbooks with deployment-strategist.

Team Topologies alignment

Map candidate services to topology types (Team Topologies):

Conway's law: research should flag misalignment when desired boundaries contradict team structure—recommend org change or fewer services.

Hand off enterprise org design to enterprise-strategist when restructuring is in scope.

Build vs buy vs managed

For each cross-cutting capability (auth, payments, search, messaging):

Document exit strategy and data portability for buy/managed options.

Anti-patterns

• Strangler without routing layer — code flags only, no traffic control
• First slice is framework — "create platform team" before value slice
• Data big-bang — one weekend migration without reconciliation
• Ignoring team topology — services no team can own on-call
• Perpetual dual-write — no retirement date for legacy path

Research deliverables and decision records

Table of contents

1. Deliverable templates 2. Options matrix 3. NFR impact table 4. ADR structure for microservice research 5. Literature and pattern comparison 6. Review and sign-off 7. Handoff to implementation

Deliverable templates

Research brief (1–3 pages)

## Question
[Decision to make]

## Constraints
[Time, teams, compliance, budget]

## Method
[Workshops, document review, benchmarks, spikes planned]

## Findings (summary)
[3–5 bullets]

## Recommendation
[Chosen option + confidence]

## Open questions
[Items blocking implementation]

Candidate service catalog

Context map summary

Attach diagram + table of edges (pattern, contract type, consistency).

Options matrix

Always include at least three rows:

1. Status quo / modular monolith (or fewer services) 2. Recommended split (or hybrid) 3. Maximum decomposition (stress test)

Weight criteria with decision owner; show scored totals only if stakeholders want numbers—avoid false precision.

NFR impact table

Per recommended boundary:

Link to senior-system-architecture for estate-wide SLO policy; to high-concurrency-scalability for load validation plans.

ADR structure for microservice research

# ADR-NNN: [Title]

## Status
Proposed | Accepted | Deprecated

## Context
[Forces and constraints]

## Decision
[What we will do]

## Options considered
### Option 1 — [name]
- Pros / Cons

### Option 2 — [name]
- Pros / Cons

## Consequences
Positive, negative, risks

## Compliance with principles
[Data ownership, team topology, contract policy]

## Follow-up
[Spikes, ADRs, owners, dates]

One-way doors (hard-to-reverse splits, public partner contracts): require architecture review with senior-system-architecture.

Literature and pattern comparison

Use citations to inform—not replace—context-specific analysis:

Comparison table when stakeholders cite conflicting patterns:

Review and sign-off

Handoff to implementation

Research package should list:

Definition of done for research: decision recorded, constraints documented, boundaries drawn, contracts policy set, migration slice #1 defined, NFR table attached, and implementation backlog created with named owners.