Architecture Decision Documentation and Communication Questions

Covers the practices for capturing, organizing, and communicating architectural decisions and the rationale behind them. Candidates should be able to describe how to create architecture decision records and design documents, record alternatives considered, list pros and cons, and show impacts on scalability, cost, maintainability, security, and operations. This topic also covers techniques for communicating decisions to engineers, product managers, and non technical stakeholders, obtaining buy in, handling feedback and dissent, and evolving documentation as requirements change. Interviewers may probe how candidates link decisions to requirements, trace implications across components, and ensure decisions are discoverable and revisited when assumptions change.

MediumTechnical

31 practiced

Role-play: during a sales cycle a client insists on a proprietary protocol they already use. As solutions architect, explain how you'd document this requirement in an ADR, evaluate alternatives, capture the client's business rationale, estimate integration effort and cost, and present a recommendation to both sales and engineering that balances client needs and product strategy.

Sample Answer

Situation: A prospective client insists our product must support their proprietary protocol to close the deal. As the solutions architect I need to evaluate feasibility, risks, cost, and recommend a path that serves the client while protecting product strategy.

Action — how I’d document and evaluate (ADR + artifacts):1. Create an Architecture Decision Record (ADR) titled “Support for ClientX Proprietary Protocol” with: - Context: client description, protocol name/version, existing integrations, business drivers (e.g., locked-in legacy systems, regulatory needs). - Decision to be made: whether and how to support the protocol (native support, adapter, gateway, third‑party bridge, or decline). - Constraints: timelines, security/compliance, performance, licensing/IP restrictions. - Alternatives considered (each with pros/cons and risk): a) Native implementation in core product — high dev cost, deep integration, long-term maintenance burden, strategic divergence. b) Pluggable adapter in SDK/extension — moderate cost, isolates product, reusable pattern. c) External gateway/middleware (customer-managed) — low product impact, higher client ops burden. d) Third-party integration partner — low product effort, dependency/risk. - Evaluation criteria: time-to-deliver, cost, maintainability, security, product roadmap alignment, reusability. - Recommendation and rationale. - Decision outcome and follow-up actions (POC, timelines, owners).

2. Capture client business rationale explicitly in the ADR and an attached one-page “Business Impact”: metrics (contract size, churn risk, strategic account value), timeline pressure, legal/contractual requirements.

3. Estimate integration effort & cost: - Produce a Work Breakdown: discovery (8-16 hours), design (16-24h), prototype/POC (40-80h), development (engineer-weeks depending on choice), testing/security review (20-40h), documentation/deployment (16-24h), support ramp (ongoing). - Translate to cost: developer hours * blended rate + QA + professional services + opportunity cost (delaying roadmap features). - Provide best/worst case ranges and clearly mark assumptions (access to protocol spec, test harness, availability of client engineers).

4. Risk & mitigations: IP/legal review if protocol proprietary, performance testing, backward compatibility, maintenance SLA and pricing for custom work.

Presentation to sales and engineering:- Sales: a succinct one-page recommendation: recommended option, estimated time-to-close increase, cost to client (fixed fee vs. recurring), negotiation levers (pilot, time-limited adapter, higher support tier), and ROI (deal value vs. implementation cost).- Engineering: a technical briefing with ADR, detailed WBS, API contracts, security checklist, and POC plan. Ask for preliminary resource commitment and gating criteria.- Dual meeting: align on a compromise — e.g., deliver a sponsored, pluggable adapter owned by the client or by Professional Services with clear roadmap guardrails; include an agreement to generalize if multiple customers request it.

Result: Decision recorded, transparent trade-offs, costed proposal for sales, and an engineering plan that minimizes long-term product risk while preserving the deal. This balances client urgency with product strategy and creates paths to productize later if demand justifies it.

HardTechnical

38 practiced

Case study: A large product team with 200 services and high release velocity is evaluating a re-architecture. As solutions architect, describe how you would evaluate monolith vs microservices vs modular monolith. Define evaluation criteria (team topology, latency, regulatory constraints, deployment independence, operational cost) and outline an ADR template that captures the analysis and recommendation.

Sample Answer

Start by clarifying constraints and goals: business drivers (time-to-market, regulatory/compliance, cost targets), run-rate release cadence, pain points (e.g., long deploy windows, cascading failures), and success metrics (lead time, MTTR, infra cost, release independence).

Evaluation criteria (with measurable signals):- Team topology (conway alignment, ownership): number of autonomous teams, code ownership boundaries, cross-team coupling (high/med/low).- Deployment independence: percentage of releases blocked by others, mean lead time per change, required coordination meetings.- Latency & performance: inter-service call latency budget, percent requests that cross services, SLOs.- Regulatory & data residency: data silo requirements, audit trails, encryption/segregation needs.- Operational cost & complexity: infra cost per request, on-call load, automation maturity (CI/CD coverage).- Developer productivity & cognitive load: PR size, time to onboard, context-switch metrics.

Evaluation method:1. Map current services to business capabilities and teams.2. Quantify signals above (metrics + developer interviews).3. Score options (Monolith / Modular Monolith / Microservices) per criterion (0-5), weight by business priority.4. Run risk analysis (security, rollout, rollback complexity) and pilot plan.

Typical trade-offs:- Monolith: low operational overhead, easier local refactor, but poor deployment independence at 200 services.- Modular monolith: single deployable but strong module boundaries — good when latency tight, regulatory data locality needed.- Microservices: max autonomy, better for independent scaling and compliance boundaries, but higher ops cost and cross-service latency.

Recommendation approach:- If teams >~20 and need independent scaling + regulatory isolation → adopt targeted microservices for high-domain boundaries; keep platform/infra to manage complexity.- If latency-critical, regulatory-heavy, or infra cost-sensitive → prefer modular monolith with strict module contracts and team ownership, evolve selectively to microservices where warranted.

ADR template (short):- Title- Context / Background (business drivers, constraints)- Decision (chosen architecture)- Alternatives considered (Monolith, Modular Monolith, Microservices)- Criteria & weighting (list with scores and raw data)- Analysis (scorecard, risks, mitigation)- Migration plan & guardrails (phases, pilot teams, cutover criteria)- Operational requirements (CI/CD, observability, SLOs, runbook)- Rollback / exit strategy- Owners & Review cadence- Date and approval signatures

Include a 3-phase migration pilot: 1) Stabilize platform/CI, 2) Modularize high-value domains, 3) Extract services with automated observability and SLOs.

MediumTechnical

55 practiced

You're deciding between CDN edge caching and an in-service cache for static user profile assets. Document the alternatives comparing cache invalidation complexity, consistency guarantees, geographic performance, estimated cost per million requests, and operational complexity. Draft the core recommendation and justify it for a global user base.

Sample Answer

Summary: Two viable patterns — CDN edge caching (public CDN like Cloudflare/Akamai/CloudFront) vs in-service cache (service-fronted cache such as regional Redis/ELB-level caching or application-layer cache). Below I compare key dimensions and give a recommendation for a global user base.

Alternatives:1) CDN edge caching- Cache invalidation complexity: Medium — supports TTLs, cache-control and soft/purge APIs. Invalidation at scale requires purge API orchestration or versioned URLs (cache-busting) to avoid mass purges.- Consistency guarantees: Eventual. Edges may serve stale objects until TTL expires or explicit purge propagates; purges are fast but not instantaneous globally.- Geographic performance: Excellent — single-digit to low-double-digit ms globally from nearest PoP.- Estimated cost / 1M requests: $0.50–$5 (request + egress; depends on CDN and region); bandwidth dominates if assets are large.- Operational complexity: Low — managed service, simple integration, fewer infra responsibilities.

2) In-service cache (regional Redis/edge application caches or nearest-AZ caches)- Cache invalidation complexity: High — need coordinated invalidation across regions, or central invalidation service; more logic in app.- Consistency guarantees: Stronger possible — can implement near-real-time invalidation (pub/sub), read-through/write-through patterns to keep caches coherent.- Geographic performance: Moderate — faster within region/availability zone; global users may see higher latency unless you deploy many regional caches.- Estimated cost / 1M requests: $5–$30 (compute + managed cache nodes + network egress if regional replication used).- Operational complexity: High — provisioning, scaling, replication, failover, and operational runbook for cache coherence.

Recommendation:Use CDN edge caching as primary delivery mechanism for static user profile assets, combined with cache-control headers and versioned asset URLs for deterministic invalidation. For assets requiring immediate consistency (e.g., profile photo changed and must be visible instantly to owner), add a short cache TTL + origin purge on update and a user-scoped cache-bypass query param for critical paths, or implement a fast synchronous invalidation flow (invalidate CDN by versioned URL). Optionally deploy regional in-service caches only for write-heavy metadata workflows needing strong consistency; keep origin storage (S3/object store) and small TTLs to minimize stale windows.

Justification:Global performance and cost favor CDN edges — lowest latency worldwide and lowest per-request cost. CDN reduces operational burden while offering pragmatic invalidation tools. Combine conservative TTLs and versioned URLs to balance eventual consistency with user expectations; reserve in-service caches where strict, low-latency consistency is required and you can absorb operational overhead.

MediumTechnical

35 practiced

Describe how to ensure ADRs include observability requirements. Provide an example ADR snippet that maps the decision 'introduce async order processing' to specific SLOs, metrics (queue depth, processing latency, error rate), dashboards, and alert thresholds tied to the decision.

Sample Answer

Approach: Treat ADRs as the single source of truth for architectural decisions and their operational impact. For each decision include a dedicated "Observability" section that maps decision goals to SLOs, the exact metrics to collect, dashboards to build (with key visualizations), alert thresholds tied to business impact, and runbook links. This makes operational requirements explicit during design, sizing, and purchase decisions.

Example ADR snippet (decision: introduce async order processing):

yaml

Title: Introduce async order processing via OrderQueue service
Status: Accepted
Date: 2025-11-22
Decision: Replace sync order submit flow with async processing using a durable FIFO queue and worker pool to improve throughput/latency isolation.
Observability:
  Objectives:
    - Preserve user-perceived order submit availability >= 99.9 (SLO)
    - Ensure end-to-end order processing within 60s for 95% of orders (SLO)
  SLOs:
    - Submit availability: successful enqueue / enqueue attempts >= 99.9% per 30d
    - Processing latency: 95th percentile end-to-end processing <= 60s (1d/7d windows)
    - Error rate: processed orders failing >= 0.5% over 1h rolling window triggers mitigation
  Metrics (implement as labeled, high-cardinality-aware):
    - queue.depth: current messages in OrderQueue (by topic, priority)
    - queue.enqueue.rate: enqueues/sec
    - queue.dequeue.rate: dequeues/sec
    - processing.latency.ms: time from enqueue -> processed (histogram)
    - processing.error.count: count of failed processing attempts, with error_type label
    - worker.utilization: percent busy per worker instance
    - dead_letter.count: messages moved to DLQ
  Dashboards:
    - "Order Queue Health" panel: time-series queue.depth, enqueue/dequeue rates, dead_letter.count
    - "Processing Latency" panel: p50/p95/p99 of processing.latency.ms + histogram heatmap
    - "Worker Pool" panel: worker.count, worker.utilization, dequeue.rate per worker
    - "Errors & DLQ" panel: processing.error.count by error_type, recent DLQ samples (links)
  Alerts (actionable, with severity & runbook):
    - P0: queue.depth > 10k for 5m AND enqueue.rate - dequeue.rate > 0 => Alert: "Backlog growing" -> page on-call, runbook: scale workers, investigate poison messages
    - P1: processing.p95 > 60s for 10m => Alert: "High processing latency" -> notify SRE, check downstream dependencies
    - P1: processing.error.count rate > 0.5% over 1h => Alert: "Increased processing errors" -> trigger rollback or routing to degraded path
    - P2: dead_letter.count increases by >100 in 15m => Alert: "DLQ spike" -> investigate message content, apply fixes
  Instrumentation notes:
    - Emit metrics with consistent labels: environment, region, sku, priority
    - Use histograms for latency with fixed buckets (0-1s,1-5s,5-30s,30-120s,>120s)
    - Trace sample when processing.latency > p95 and when errors occur; link traces in dashboards
  Runbooks:
    - Link: /runbooks/orderqueue/backlog-incident
    - Link: /runbooks/orderqueue/error-investigation
  Reviews:
    - Operational acceptance required: SRE sign-off on metrics/dashboards before rollout

Why this works:- Ties architectural intent (throughput, UX) to measurable SLOs so decisions are validated in production.- Specifies concrete metrics, dashboard panels and alert thresholds making monitoring implementable and testable.- Ensures operational readiness via runbooks and SRE sign-off, reducing rollout friction and aligning stakeholders.

MediumTechnical

35 practiced

Write an ADR that selects an API versioning strategy for a public REST API. Compare URL versioning (/v1), header versioning, and content negotiation. Document compatibility guarantees, deprecation policy and windows, client migration path, and automated tests required to validate backward compatibility.

Sample Answer

Decision: Use URI-based versioning (/vN) as the primary public REST API versioning strategy, with optional Content-Type-based media versioning (content negotiation) for non-breaking, incremental feature rollouts. Header-only versioning is not recommended as the primary public surface.

Context:- Public, externally consumed REST API used by many third parties with diverse clients.- Need clear discoverability, simple caching/HTTP behavior, predictable breaking-change surface, and easy onboarding for non-technical integrators.

Options considered:1. URL versioning (/v1/resource) - Pros: Highly discoverable, easy to route and cache, visible in docs and examples, simple for firewalls/CDNs and analytics. - Cons: Encourages coarse-grained versions; can duplicate code if not designed for reuse.2. Header versioning (X-API-Version or custom header) - Pros: Keeps URLs stable, finer-grained control. - Cons: Hidden from common tooling, harder for simple clients (curl/browsers), caching complexity, lower adoption by public integrators.3. Content negotiation (Accept: application/vnd.company.v1+json) - Pros: Supports feature-level evolution and backward-compatible additive changes; fine-grained control. - Cons: More complex for clients, harder to test/curl, caching nuance.

Recommendation and rationale:- Primary: URI versioning (/v1) for major breaking changes. It provides clarity to external integrators, reduces accidental breakage, and aligns with CDN/caching and monitoring.- Secondary: Use media-type versioning (Accept/Content-Type) within a major version for additive, non-breaking feature flags or opt-in fields. Avoid header-only versioning for public docs; consider it internally for routing or internal consumers.

Compatibility guarantees:- Within a major version (e.g., /v1): maintain backward compatibility for existing endpoints and fields. Only additive, non-breaking changes allowed (new optional fields, new endpoints). Remove or change behavior only in major releases.- Major version bump (e.g., /v2) permits breaking changes; migration required.

Deprecation policy and windows:- Announce deprecations at least 90 days before sunset for minor non-critical removals; 12 months for major behavioral changes. Policy: 1. Deprecation notice posted in API response headers (Warning, Deprecation) and developer portal immediately. 2. Migration guides and changelog published within 7 days of notice. 3. Support and dual-running: maintain old major version for minimum 12 months after vN+1 launch (shorter windows only with explicit customer agreement). 4. If critical security fixes required, provide patch releases; avoid unannounced breaking patches.

Client migration path:- For breaking changes (major version): - Provide migration guide mapping old -> new endpoints, field mapping, and code snippets. - Provide a compatibility shim or proxy for common SDK languages where feasible. - Offer an endpoint comparison tool and an opt-in feature-flagged trial period.- For additive changes: - Document new fields; clients can ignore unknown fields per robust JSON parsing guidance.- Communication: email, portal announcements, API responses with deprecation headers, and SDK updates.

Automated tests to validate backward compatibility:- Contract tests (Consumer-Driven Contracts like Pact): ensure consumers’ expected contracts run against provider; run in CI on each change.- Schema validation/diff: maintain canonical JSON Schema/OpenAPI spec per version; CI fails on breaking schema diffs within same major version.- Integration tests: run representative end-to-end tests against staging that exercises real client scenarios.- Regression tests: record and replay critical request/response flows for each major client.- API linting/gating: pre-commit or CI checks enforce no-removal of documented fields within major version; require opt-in flag for any change that would violate compatibility rules.- Monitoring and telemetry: runtime checks for client error-rate spikes after deployments; automated alerts if 4xx/5xx for specific user-agents increase.

Trade-offs:- URI versioning slightly duplicates endpoints and increases routing complexity; mitigated by shared service implementation and modular controller/version layers.- Media-type versioning provides flexibility but increases client complexity; limited to opt-in or advanced integrations.

Conclusion:Use /vN URIs for major version boundaries and media-type negotiation for non-breaking, opt-in enhancements. Enforce compatibility via automated contract/schema checks and a clear, well-communicated deprecation policy with a 12-month minimum major-version support window.

Unlock Full Question Bank

Get access to hundreds of Architecture Decision Documentation and Communication interview questions and detailed answers.

Join thousands of developers preparing for their dream job.