System Architecture Design, Review, and ADRs
Turns requirements into a sized system design: component boundaries, data flow, failure modes, and ADRs with rejected alternatives.
Before & after
Same prompt, same agent — the only difference is the skill.
Decomposing a monolith is a complex undertaking, and there are definitely different approaches you could take. The key is to do it gradually so you don't break things. You'll probably want to identify the different services within your codebase, figure out the dependencies between them, and then think about how to separate them incrementally. Strangler fig pattern is one approach that some companies use. You'll need to set up API boundaries, maybe implement an API gateway. Testing will be critical. It depends a lot on your current architecture, your team size, and how risk-tolerant you are. What does your current monolith look like? Understanding the structure would help me give more specific guidance.
ARCHITECTURE DECISION RECORD: Monolith-to-Microservices DEPENDENCY MAP (current state) • Auth service (users, sessions) → heavily coupled to 12 endpoints • Payment service (stripe integration) → 6 endpoints depend on it • Reporting service (read-only, analytics) → 2 tables, no other dependencies CRITICAL PATH: Auth + Payment → extract these first EXTRACTION ROADMAP (Phase 1: No downtime) MONTH 1: Reporting microservice BOUNDARY: Read-only copy of analytics table, async replication RISK: Low (no writes, can roll back instantly) GATE: Dual-read first 2 weeks, cutover after accuracy validation MONTH 2-3: Payment microservice BOUNDARY: All stripe calls routed through new service RISK: Medium (financial impact if wrong) GATE: Circuit breaker + fallback to monolith for 4 weeks DEPENDENCY: Needs auth service stable first MONTH 3-4: Auth microservice BOUNDARY: Session storage, token validation → separate DB RISK: High (all requests flow through) GATE: Strangler pattern—new clients call microservice, legacy traffic stays in monolith METRICS: Monitor token latency (<50ms), error rate (<0.1%) TECH CHOICES • Inter-service communication: gRPC (low latency for auth) • API gateway: Nginx (route by path prefix) • Data sync: Postgres CDC (logical replication, eventual consistency) SUCCESS CRITERIA: All three services extractable by Month 4, zero downtime events, <5ms added latency.
About this skill
Ask for an architecture and you often get twelve boxes, Kafka, and microservices for an app doing 20 requests a second. Services split by noun end up sharing tables and calling each other in chains, and nobody has written down what happens when the payment provider is slow. This skill does the math first. It draws boundaries where each piece of data has one owner, and it records every major decision with the options that lost.
What it does
- Sizes the system before shaping it: average and peak RPS split into reads and writes, storage growth, and an availability target converted into a downtime budget
- Pushes back when the premise is wrong for your numbers, for example microservices for a team of six, or 99.99% on a single region
- Draws service boundaries by data ownership, with one writer per entity and a test for whether a service is really separate
- Builds a failure-mode table for every dependency: timeout, bounded retry, fallback, and what the user sees
- Catches distributed-system traps: dual writes, non-idempotent consumers, retry storms, hot partitions, and long sync chains
- Writes ADRs that list the alternatives considered, the costs you accept, and a measurable trigger for revisiting the decision
What you get
You get a design sized to your load: sizing numbers, a Mermaid diagram that marks sync and async flows, a data-ownership table, key flows, a failure-mode table, and ADRs. For a pasted design, you get review findings ranked by severity, each with a concrete fix.
Best for
This is for tech leads, staff engineers, and founders who need to design a new service, decide whether to split a monolith, review a design doc before build, or record a technology choice the team will still understand in a year.
SKILL.md preview
---
name: system-architecture-design-and-adrs
description: Designs and reviews system architecture from quantified requirements. Covers back-of-envelope sizing, data-ownership boundaries, sync vs async flows, failure-mode analysis, and ADRs that record rejected alternatives and revisit triggers. Use when the user says "design the architecture for our new service", "should we split this into microservices", "review our system design", "write an ADR for Kafka vs SQS", "will this scale to 10x", "our services keep timing out in a chain", or "we have a distributed monolith and every deploy breaks something".
---
# System Architecture Design, Review, and ADRs
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.