decision-makingestablished · low burden
Capture a significant architectural decision with its context, alternatives considered, and consequences — creating a searchable, reviewable decision history.
✓ Any decision expensive to reverse (data model, protocol, cloud provider, framework)✓ Decisions affecting multiple teams or services✓ When you'd want to explain 'why' to a new hire in 6 months✗ Tactical coding decisions (variable names, library versions)✗ Decisions already captured in RFCs or design docs
architecture-descriptionestablished · low burden
Foundational principles for designing consistent, evolvable, developer-friendly APIs — beyond syntax to architecture.
✓ Any team building APIs✓ Multiple teams, multiple consumers✓ Public or partner APIs✗ Internal RPC (gRPC better)✗ Throwaway prototypes
architecture-descriptionestablished · low burden
Design consistent, evolvable, developer-friendly REST APIs using standard conventions.
✓ Any team building REST APIs✓ Public or partner APIs✓ Multiple consumers (web, mobile, third-party)✗ Internal RPC (gRPC better)✗ GraphQL APIs (different paradigm)
security-complianceestablished · medium burden
Centralize authentication at the API Gateway: JWT validation, API keys, OAuth2 introspection, mTLS — patterns for security and performance.
architecture-descriptionestablished · medium burden
Common patterns for API Gateway usage: BFF, aggregation, protocol translation, security enforcement.
✓ Multiple client types with different needs✓ Cross-cutting concerns centralized✓ Protocol translation required✗ Single client, simple services✗ Team not ready for gateway ownership
architecture-descriptionestablished · medium burden
Single entry point for clients that handles cross-cutting concerns: routing, auth, rate limiting, observability, protocol translation.
✓ Multiple services exposed to external clients✓ Need centralized auth, rate limiting, observability✓ Protocol translation required✗ Single service (no routing needed)✗ Internal service-to-service (use service mesh)
architecture-descriptionestablished · medium burden
Evolve APIs without breaking existing clients, using explicit versioning strategy.
✓ Public APIs with external consumers✓ Multiple client teams (mobile, web, partners)✓ Long-lived APIs with evolving requirements✗ Internal APIs with coordinated deploys✗ Single consumer (version in sync)
decision-makingestablished · low burden
Capture significant architectural decisions with context, alternatives, and consequences — creating searchable, reviewable decision history.
✓ Any team making architectural decisions✓ Team growing beyond tribal knowledge✓ Regulatory/audit requirements✗ Solo developer (personal notes sufficient)✗ Team with perfect memory and zero turnover
decision-makingestablished · medium burden
Structured architecture review: lightweight, scalable, decision-focused — preventing rubber-stamp approvals and ensuring trade-offs are explicit.
✓ Team > 5 engineers✓ Cross-team dependencies increasing✓ Architecture decisions causing incidents✗ Small team (<5), low complexity✗ Pre-product (velocity > process)
distribution-communicationestablished · high burden
Choose the right async communication pattern: fire-and-forget, request-reply, pub/sub, streaming — trade-offs for coupling, latency, and reliability.
✓ Decouple services (deploy independently)✓ Variable workloads (burst absorption)✓ Multiple consumers for same event✗ Simple request-response (sync HTTP fine)✗ Strong consistency required (distributed tx)
architecture-descriptionestablished · low burden
Orchestrate serverless workflows as state machines with built-in retries, error handling, parallel execution, and visual debugging — no servers to manage.
✓ Serverless orchestration (Lambda, ECS, API calls)✓ Long-running processes with retries, human approval✓ Visual debugging and audit trail required✗ Complex logic better in code (Temporal better)✗ Sub-second latency (Express: 5min max)
resilienceestablished · low burden
Signal upstream to slow down when downstream cannot keep up, preventing buffer overflow and cascade failure.
✓ Streaming data: logs, metrics, events, file uploads✓ Async pipelines with variable throughput✓ Reactive systems (Project Reactor, RxJava, Akka Streams)✗ Request-response (synchronous, natural backpressure)✗ Low throughput where buffering is fine
deploymentestablished · medium burden
Run two identical environments (blue, green). Switch traffic atomically for zero-downtime deployments with instant rollback.
✓ Zero-downtime requirement✓ Instant rollback critical✓ Infrastructure supports duplicate envs (K8s namespaces, ASGs)✗ Stateful services without session handling✗ Breaking schema changes (need expand/contract)
resilienceestablished · medium burden
Isolate critical resources (threads, connections, memory) so failure in one component doesn't starve others.
✓ Caller has multiple downstreams with different SLAs✓ Critical path must stay responsive during non-critical downstream issues✓ Prevent noisy neighbor problem in shared infrastructure✗ Single downstream (circuit breaker sufficient)✗ Very low throughput where isolation overhead exceeds benefit
architecture-descriptionestablished · low burden
A hierarchical notation for describing software architecture at four levels of abstraction, optimising for different audiences and decision contexts.
✓ Any architecture documentation that needs to be maintained✓ Design reviews where stakeholders have varied technical depth✓ Onboarding new team members to system structure✗ Throwaway prototypes or spike investigations✗ Infrastructure-only diagrams (use cloud provider notation)
scalingestablished · low burden
Store frequently accessed computed or fetched data in fast storage to reduce latency and downstream load.
✓ Hot data: config, reference data, computed aggregates✓ Expensive computations: recommendations, ML inference✓ Downstream protection: reduce DB/third-party load✗ Write-heavy, low-read data✗ Strong consistency required (financial balances)
deploymentestablished · medium burden
Gradually shift traffic to new version, monitoring for regressions before full rollout.
✓ Continuous deployment pipeline✓ Risky changes: schema, algorithm, third-party upgrade✓ User-facing services with measurable metrics✗ Infrastructure changes (no traffic to split)✗ Single-instance services (no parallel versions)
economics-evolutionestablished · medium burden
Predict resource needs (CPU, memory, storage, network) for future load, enabling proactive scaling and cost optimization.
✓ Growing systems (user base, data, features)✓ Cost optimization initiatives✓ Preparing for known events (Black Friday, launch)✗ Stable, predictable workloads✗ Serverless (capacity managed by provider)
data-consistencyestablished · high burden
Capture database changes (insert/update/delete) in real-time and stream them to downstream systems.
✓ Real-time analytics, search indexing, cache invalidation✓ Event sourcing / CQRS projection updates✓ Audit logging, compliance✗ Low change volume (polling simpler)✗ Database doesn't support logical replication
architecture-descriptionemerging · high burden
Partition system into independent cells (tenants, regions, shards) so failure in one cell doesn't affect others, enabling safe deployments and blast radius control.
✓ High availability requirements (99.99%+)✓ Regulatory data residency✓ Large-scale SaaS (1000+ tenants)✗ Small systems (<10 cells)✗ Strong cross-tenant consistency needed
architecture-descriptionemerging · high burden
Partition system into independent cells (tenants, regions, shards) so failure in one cell doesn't affect others.
✓ High availability requirements (99.99%+)✓ Regulatory data residency✓ Large-scale SaaS (1000+ tenants)✗ Small systems (<10 cells)✗ Strong cross-tenant consistency needed
reliability-opsemerging · high burden
Proactively inject failures to discover weaknesses before they cause outages, building confidence in system resilience.
✓ High availability targets (99.99%+)✓ Post-incident: prevent recurrence✓ Before major launches or migrations✗ No observability (blind injection)✗ No rollback/autostop mechanism
resilienceestablished · low burden
Prevent cascading failures by stopping requests to a failing service, giving it time to recover.
✓ Any synchronous remote call (HTTP, gRPC, DB)✓ Downstream services with variable latency or reliability✓ When caller must remain responsive during downstream outage✗ Local in-process calls (no network failure mode)✗ Fire-and-forget async operations
scalingestablished · low burden
Distribute keys across nodes with minimal reshuffling when nodes join/leave, using a hash ring with virtual nodes.
✓ Dynamic node membership (add/remove nodes)✓ Distributed cache or sharding✓ Minimal reshuffle on scaling✗ Static cluster (simple hash % N fine)✗ Small N (<5) where distribution skew matters
architecture-descriptionestablished · medium burden
Ensure provider changes don't break consumers by making consumers define their expectations as executable contracts.
✓ Microservices with independent deployments✓ Multiple consumers per provider✓ Breaking changes cause production incidents✗ Monolith or few services with coordinated deploys✗ Public APIs with unknown consumers
economics-evolutionemerging · high burden
Continuously reduce cloud spend while maintaining performance and reliability, using unit economics and architectural choices.
✓ Cloud spend > $10k/month✓ Finance asking for cost accountability✓ Architectural decisions need cost input✗ Pre-revenue (optimize for velocity)✗ Tiny spend (<$1k/month)
architecture-descriptionestablished · high burden
Separate read and write models to optimize each: writes for consistency, reads for query performance and flexibility.
✓ Read/write patterns differ significantly✓ Complex queries on normalized data✓ Different scaling needs (read replicas vs write primary)✗ Simple CRUD with straightforward queries✗ Strong consistency required between read/write
architecture-descriptionestablished · high burden
Separate read and write models to optimize each for its specific concerns: writes for consistency, reads for query performance.
✓ Read/write patterns differ significantly✓ Complex queries on normalized data✓ Different scaling needs (read replicas vs write primary)✗ Simple CRUD with straightforward queries✗ Strong consistency required between read/write
data-stateestablished · medium burden
Design scalable, maintainable data models: normalization, denormalization, entity relationships, temporal data, polymorphic associations.
✓ Any system with relational data✓ Schema evolution without downtime✓ Query performance optimization✗ Document/NoSQL primary (different patterns)✗ Team not ready for modeling discipline
data-stateestablished · medium burden
Design indexes that accelerate queries without killing write performance, using covering indexes, partial indexes, and query-driven design.
✓ Any production database with query performance needs✓ Write-heavy tables (index carefully)✓ Query patterns changing✗ Tiny tables (seq scan faster)✗ Append-only logs (few queries)
data-consistencyestablished · high burden
Evolve database schema without downtime or locking, using backward-compatible multi-phase migrations.
✓ Any schema change on tables with >1M rows✓ Zero-downtime deployments required✓ Blue-green or canary deployments✗ Small tables, maintenance window acceptable✗ Breaking changes that can't be phased (rare)
resilienceestablished · medium burden
Capture messages that fail processing repeatedly for later inspection and replay, preventing pipeline blockage.
✓ Any async message processing system✓ Message failures are expected (bad data, transient bugs)✓ Need visibility into failure patterns✗ Synchronous request-response (no queue)✗ Fire-and-forget where loss is acceptable
deploymentestablished · high burden
Choose and implement safe deployment strategies: rolling, blue-green, canary, feature flags — with automated rollback and observability.
✓ Any production deployment✓ Zero-downtime requirements✓ Risk mitigation for changes✗ Dev/test environments (rolling fine)✗ Single-instance services (no HA)
reliability-opsestablished · high burden
Define and practice recovery from catastrophic failures: region loss, data corruption, ransomware, ensuring RTO/RPO targets are met.
✓ Any production system with availability requirements✓ Regulatory: DR mandated (finance, healthcare, gov)✓ Customer contracts specify RTO/RPO✗ Dev/test environments✗ Systems where data loss/downtime acceptable
coordinationestablished · low burden
Coordinate access to shared resource across distributed processes, ensuring mutual exclusion with fault tolerance.
✓ Singleton task across multiple instances✓ Leader election for HA services✓ Coordination without message broker✗ High-contention hot paths (use partitioning)✗ Long-held locks (minutes+) — prefer leases
observabilityestablished · medium burden
Track request flow across service boundaries to understand latency, errors, and dependencies.
✓ Any distributed system (>3 services)✓ Latency debugging across service boundaries✓ Error root cause analysis✗ Monolith or 2-service system (logs sufficient)✗ Ultra-high throughput where sampling loses signal
data-consistencyestablished · high burden
Coordinate atomic operations across services without distributed locks: 2PC, Saga, Outbox, Eventual Consistency — trade-offs and implementation.
✓ Microservices needing cross-service atomicity✓ Long-running business processes✓ Event-driven architectures✗ Simple CRUD (single service)✗ Strong consistency required everywhere (monolith)
architecture-descriptionestablished · high burden
Decouple services through asynchronous event communication, enabling independent scaling, deployment, and evolution.
✓ Microservices needing loose coupling✓ Audit trail, replay, temporal queries✓ Polyglot services (different languages)✗ Simple request-response (REST/gRPC fine)✗ Strong consistency required (distributed transactions)
data-consistencyestablished · high burden
Persist state changes as immutable event log, enabling audit trail, temporal queries, replay, and multiple read models.
✓ Audit/regulatory requirements (financial, healthcare, gov)✓ Complex domain with rich business events✓ Need temporal queries (state at date X)✗ Simple CRUD with no audit needs✗ High-throughput, low-latency writes (event store adds overhead)
data-consistencyestablished · high burden
Persist state changes as an immutable sequence of events, enabling complete audit trail, temporal queries, and rebuild of state.
✓ Audit/regulatory requirements (financial, healthcare, gov)✓ Complex domain with rich business events✓ Need temporal queries (state at date X)✗ Simple CRUD with no audit needs✗ High-throughput, low-latency writes (event store adds overhead)
deploymentestablished · medium burden
Operational patterns for feature flags: naming, lifecycle, cleanup, testing, avoiding flag debt.
✓ Continuous deployment with feature flags✓ Team has >20 flags✓ Flag debt causing bugs✗ No feature flags (simple deploys)✗ Team not ready for hygiene process
deploymentestablished · low burden
Decouple deployment from release. Enable/disable features at runtime without code deploy.
✓ Continuous deployment (deploy ≠ release)✓ A/B testing, gradual rollout✓ Kill switches for risky dependencies✗ Simple deployments (no branching needed)✗ Flags that live forever (tech debt)
architecture-descriptionestablished · high burden
Design performant, secure, evolvable GraphQL APIs: schema design, N+1 prevention, complexity limiting, caching, versioning.
✓ Multiple clients with diverse data needs✓ Rapid frontend iteration (backend stable)✓ Complex relationships (graph-shaped data)✗ Simple CRUD (REST simpler)✗ Public APIs with unknown consumers
architecture-descriptionestablished · high burden
Compose multiple GraphQL services into a single unified graph, enabling independent service ownership with unified client queries.
✓ Multiple teams owning GraphQL services✓ Clients need cross-domain queries✓ Schema evolution without coordination✗ Single team, single GraphQL service✗ Simple REST APIs sufficient
distribution-communicationestablished · medium burden
Design efficient, evolvable gRPC services: unary, streaming, errors, versioning, gateway, testing.
✓ Internal service-to-service (low latency, high throughput)✓ Polyglot microservices (codegen per language)✓ Streaming required (real-time, bulk)✗ Public APIs (REST/GraphQL better)✗ Simple CRUD (REST simpler)
messagingestablished · low burden
Make any operation safely retryable by attaching a unique client-generated key that the server uses to detect and ignore duplicates.
✓ Any write operation exposed to retries (payments, orders, reservations)✓ Webhook endpoints receiving at-least-once delivery✓ API endpoints where clients implement retry logic✗ Read-only operations (GET is naturally idempotent)✗ Operations where duplicates are harmless or desired
data-consistencyestablished · low burden
Make operations safely retryable using idempotency keys, natural idempotency, and idempotent receivers — preventing duplicate side effects.
✓ Any POST/PATCH/DELETE exposed to retries✓ Webhook endpoints (at-least-once delivery)✓ Payment, order, reservation systems✗ GET (naturally idempotent)✗ High-throughput internal RPCs (exactly-once infra)
reliability-opsestablished · high burden
Structured incident response: detection, response, resolution, postmortem — reducing MTTR and preventing recurrence.
✓ Any production system with on-call✓ Team experiencing burnout or high MTTR✓ Repeated incidents, no learning✗ Pre-production (lightweight process)✗ Single-person team (simplify)
architecture-descriptionestablished · high burden
Design reliable, scalable Kubernetes applications: pod design, resource management, deployment strategies, observability, security.
✓ Containerized workloads at scale✓ Team ready for operational complexity✓ Multi-cloud / hybrid deployment needs✗ Simple workloads (ECS Fargate, Cloud Run simpler)✗ Team not ready for ops complexity
coordinationestablished · low burden
Ensure exactly one instance performs a task (scheduler, processor, migrator) in a distributed system.
✓ Singleton background tasks (scheduler, migrator, aggregator)✓ Active-passive failover for stateful services✓ Distributed cron jobs✗ Stateless horizontal scaling (all instances should work)✗ Tasks that can run concurrently (partition instead)
distribution-communicationestablished · medium burden
Choose the right load balancing algorithm: round-robin, least connections, least latency, consistent hashing — trade-offs for latency, distribution, and session affinity.
✓ Any service with multiple instances✓ Heterogeneous fleet (different instance types)✓ Session affinity needed (legacy apps)✗ Single instance✗ Stateless, homogeneous, low scale (round-robin fine)
resilienceestablished · medium burden
Under overload, selectively drop low-priority requests to preserve capacity for high-priority work.
✓ Traffic spikes exceed provisioned capacity✓ Multi-tenant: protect paying customers✓ Critical paths must stay available (payments, auth)✗ All requests equally critical✗ Capacity planning sufficient (rare spikes)
scalingestablished · medium burden
Pre-compute and store query results for fast reads, refreshed periodically or on data change.
✓ Complex aggregations, joins, window functions✓ Dashboard, reporting, user-facing analytics✓ Data freshness: minutes to hours OK✗ Real-time consistency required✗ Ad-hoc queries (unpredictable patterns)
security-complianceestablished · medium burden
Authenticate both client and server in every connection using certificates, enabling zero-trust service-to-service communication.
✓ Service-to-service communication in zero-trust✓ Regulatory: encryption in transit required✓ Multi-cluster, hybrid cloud✗ External APIs (clients can't do mTLS easily)✗ Legacy services that can't terminate TLS
architecture-descriptionestablished · high burden
Share infrastructure across customers while isolating data, compute, and blast radius — patterns from shared DB to dedicated clusters.
✓ SaaS with >10 tenants✓ Regulatory data isolation (GDPR, HIPAA, FedRAMP)✓ Noisy neighbor risk (variable tenant load)✗ Single-tenant (dedicated deployment)✗ Very few tenants where dedicated is cheaper
observabilityestablished · high burden
Build comprehensive observability: three pillars + SLI/SLO, alerting, debugging workflows, cost control.
✓ Any production distributed system✓ Incident response: MTTR targets✓ Capacity planning: saturation signals✗ Simple monolith (logs + basic metrics sufficient)✗ Team not ready for instrumentation investment
observabilityestablished · high burden
Understand system internal state through external outputs: metrics (what), logs (why), traces (where).
✓ Any production distributed system✓ Incident response: MTTR targets✓ Capacity planning: saturation signals✗ Simple monolith (logs + basic metrics sufficient)✗ Team not ready for instrumentation investment
data-consistencyestablished · low burden
Prevent lost updates in concurrent writes without blocking, using version numbers or timestamps to detect conflicts.
✓ Low conflict rate (<1% of writes)✓ Read-heavy workloads✓ Distributed systems (no distributed lock needed)✗ High conflict rate (pessimistic better)✗ Long transactions (version changes during read)
data-consistencyestablished · medium burden
Guarantee atomic database update + message publish without distributed transactions, using an outbox table and relay.
✓ Any service that must publish events after DB changes✓ Microservices needing reliable event-driven communication✓ When 2PC is unavailable or undesirable✗ Single-service deployments with embedded broker (rare)✗ When eventual consistency of seconds is unacceptable
architecture-descriptionestablished · low burden
Return large result sets in pages efficiently, avoiding performance cliffs and consistency issues.
✓ Any list endpoint returning >100 items✓ Concurrent writes to collection✓ Performance matters (mobile, infinite scroll)✗ Small, static datasets (<100 items)✗ Random access required (page 50 directly)
scalingestablished · high burden
Choose and implement partitioning strategy: hash, range, directory, consistent hashing — trade-offs for distribution, resharding, and query routing.
✓ Data > single node capacity (storage, CPU, connections)✓ Throughput > single node (100k+ QPS)✓ Multi-tenant isolation required✗ Single node sufficient with headroom✗ Complex cross-shard queries (joins, transactions)
scalingestablished · high burden
Distribute data and load across multiple nodes by partitioning on a key, enabling horizontal scale beyond single-node limits.
✓ Data size > single node capacity (TB+)✓ Throughput > single node (100k+ QPS)✓ Multi-tenant isolation required✗ Data fits on one node with room to grow✗ Complex cross-partition queries (joins, transactions)
economics-evolutionemerging · high burden
Build an Internal Developer Platform (IDP) that reduces cognitive load for stream-aligned teams through self-service, golden paths, and abstraction — not a ticket queue.
✓ Stream-aligned teams > 5✓ Teams reinventing CI/CD, K8s, observability✓ Cognitive load complaints from stream teams✗ Small org (<5 stream teams)✗ Teams happy with current tooling
resilienceestablished · low burden
Compare rate limiting algorithms: token bucket, leaky bucket, fixed window, sliding window — trade-offs and use cases.
✓ Any rate limiting implementation✓ Choosing algorithm for new limiter✓ Debugging rate limiter behavior✗ No rate limiting needed✗ Team not implementing limiter
resilienceestablished · low burden
Control request rate to protect downstream services, enforce quotas, and prevent abuse.
✓ Public APIs (prevent abuse, enforce tiers)✓ Internal services (protect downstream, fair sharing)✓ Login/auth endpoints (prevent brute force)✗ Internal high-throughput paths where latency budget is microseconds✗ When backpressure via queueing is more appropriate
scalingestablished · medium burden
Scale read throughput by replicating data to follower nodes that serve read queries, while primary handles writes.
✓ Read-heavy workloads (analytics, reporting, user-facing reads)✓ Can tolerate eventual consistency for reads✓ Need to offload long-running queries from primary✗ Write-heavy workloads✗ Strong consistency required for all reads
data-stateestablished · high burden
Copy data across database nodes for availability, read scaling, and disaster recovery, understanding sync vs async trade-offs.
✓ Any production database needing HA✓ Read scaling (async replicas)✓ Geo-distribution (async cross-region)✗ Dev/test (single node fine)✗ Team not ready for failover drills
resilienceestablished · low burden
Handle transient failures by retrying with increasing delays, avoiding thundering herd and giving downstream time to recover.
✓ Idempotent operations (GET, PUT with idempotency key)✓ Transient failure scenarios: network, throttling, brief unavailability✓ Combined with circuit breaker (retry while closed, fail fast when open)✗ Non-idempotent operations without idempotency key✗ Permanent errors (4xx except 429, invalid input)
reliability-opsestablished · medium burden
Documented, step-by-step procedures for common operational tasks and incident response, reducing MTTR and cognitive load during incidents.
✓ Any production service✓ On-call rotation exists✓ Incident MTTR > target✗ Pre-production environments✗ Fully automated self-healing (no human needed)
data-consistencyestablished · high burden
Manage distributed transactions across services without 2PC, using a sequence of local transactions with compensating actions.
✓ Long-running business processes across service boundaries✓ When eventual consistency is acceptable (seconds to minutes)✓ When 2PC is unavailable or undesirable✗ Short-lived operations where synchronous ACID works✗ When strong consistency is required (financial ledger)
data-consistencyestablished · high burden
Manage distributed transactions across services without 2PC, using choreography (events) or orchestration (central coordinator) with compensating actions.
✓ Long-running business processes across service boundaries✓ When eventual consistency is acceptable (seconds to minutes)✓ When 2PC is unavailable or undesirable✗ Short-lived operations where synchronous ACID works✗ When strong consistency is required (financial ledger)
security-complianceestablished · low burden
Harden HTTP responses with security headers to mitigate XSS, clickjacking, MIME sniffing, and other client-side attacks.
✓ All public-facing web applications✓ API endpoints serving HTML/JS✓ Compliance: PCI DSS, HIPAA, SOC2✗ Internal APIs (no browser)✗ Legacy apps with inline scripts everywhere (CSP hard)
security-complianceestablished · high burden
Comprehensive security patterns: authentication, authorization, encryption, secrets, supply chain, runtime — defense in depth.
✓ Any production system✓ Regulatory requirements (SOC2, PCI, HIPAA, GDPR)✓ Customer trust is business critical✗ Pre-product (security debt acceptable)✗ Team not ready for security investment
architecture-descriptionestablished · medium burden
Design reliable, cost-effective serverless systems: function design, cold starts, orchestration, observability, cost optimization.
✓ Event-driven, bursty, unpredictable workloads✓ Team wants minimal ops overhead✓ Pay-per-use aligns with business model✗ Constant high throughput (EC2/ECS cheaper)✗ Sub-10ms latency requirements
distribution-communicationestablished · medium burden
Enable services to find each other dynamically in distributed systems, supporting scaling, failures, and deployments.
architecture-descriptionestablished · high burden
Dedicated infrastructure layer for service-to-service communication: mTLS, traffic management, observability, resilience — without application code changes.
✓ 50+ services with complex service-to-service communication✓ Need consistent mTLS without app changes✓ Platform team owns infrastructure, app teams own business logic✗ Small number of services (<20)✗ Team lacks platform engineering capacity
observabilityestablished · medium burden
Define reliability in business terms: what to measure (SLI), what's acceptable (SLO), and how much unreliability you can spend (error budget).
✓ Any service with reliability requirements✓ Teams arguing about reliability vs features✓ Need data-driven prioritization✗ Pre-product-market fit (no users to disappoint)✗ Internal tools with no SLA
observabilityestablished · low burden
Emit logs as structured data (JSON) with consistent fields, enabling querying, alerting, and correlation across services.
✓ All services in distributed system✓ Centralized log aggregation✓ Alerting on log patterns (error rates, latency)✗ Local development (pretty console output preferred)✗ Extremely high-frequency internal loops (use metrics)
economics-evolutionestablished · high burden
Design team structures that optimize for flow, autonomy, and cognitive load — applying Team Topologies patterns (stream-aligned, platform, enabling, complicated-subsystem).
✓ Org > 50 engineers✓ Cross-team dependencies slowing delivery✓ Platform team becoming bottleneck✗ Small org (<30 engineers)✗ Single product, simple domain
economics-evolutionestablished · medium burden
Systematically identify, prioritize, and pay down technical debt — treating it as a portfolio with interest rates, not a dirty word.
✓ Any team with codebase > 6 months old✓ Velocity declining, bugs increasing✓ Onboarding new engineers takes months✗ Pre-product-market fit (velocity > quality)✗ Team not ready for measurement discipline
architecture-descriptionemerging · medium burden
Write reliable, long-running business logic as code that survives crashes, retries automatically, and provides full observability — without managing queues, state machines, or timers manually.
✓ Long-running business processes (orders, onboarding, claims)✓ Human-in-the-loop workflows (approvals, reviews)✓ Reliable orchestration of microservices✗ Simple request-response (overhead not justified)✗ Sub-second latency requirements (workflow overhead)
architecture-descriptionestablished · high burden
Share infrastructure across customers while isolating their data, compute, and blast radius.
✓ SaaS with >10 tenants✓ Regulatory data isolation (GDPR, HIPAA, FedRAMP)✓ Noisy neighbor risk (variable tenant load)✗ Single-tenant (dedicated deployment)✗ Very few tenants where dedicated is cheaper
distribution-communicationestablished · medium burden
Enable real-time server-to-server notifications via HTTP callbacks, avoiding polling.
✓ Third-party integrations (Stripe, GitHub, Slack)✓ Cross-organization event notification✓ Consumer-controlled endpoints✗ High-throughput internal services (use message broker)✗ Consumer can't receive HTTP (firewall, no public endpoint)
security-complianceemerging · high burden
Never trust, always verify. Authenticate and authorize every request based on identity and context, not network location.
✓ Remote/hybrid workforce✓ Multi-cloud, hybrid infrastructure✓ Regulatory: zero trust mandated (FedRAMP, NIST 800-207)✗ Simple, on-prem only, small attack surface✗ Legacy apps that can't do mTLS/OIDC
