Menu
Design systems at the right scale with explicit trade-off documentation
Build UIs that work for all users including keyboard navigation, screen readers, and WCAG 2.2
Design multi-agent systems with robust tool interfaces, state management, and failure handling
Build ML systems with disciplined training, evaluation, deployment, and safety practices
Design APIs that are stable, ergonomic, and evolvable
Design services that are reliable, observable, secure, and maintainable
Design CI/CD pipelines with fast feedback, quality gates, and reliable deployments
| name | architecture-design |
| description | Design systems at the right scale with explicit trade-off documentation |
| difficulty | staff |
| domains | ["general"] |
Architecture design is the discipline of making the decisions that are hard to reverse later. Good architecture is not the most elegant — it is the simplest design that satisfies constraints today and can be evolved tomorrow. Every architecture decision has costs; this skill makes them explicit.
List: scale targets, latency requirements, consistency requirements, team size, deployment environment, budget, regulatory constraints. Architecture that ignores constraints is fiction.
Rank the system's quality attributes in priority order: availability, consistency, latency, throughput, security, maintainability, cost. You cannot optimize all of them — make the trade-offs explicit.
Identify the major components and their responsibilities. Apply the Single Responsibility Principle at the system level: each component should own one thing well.
Draw how data moves through the system. Where does it originate? Where is it stored? Where is it transformed? Where does it exit? This reveals coupling and bottlenecks.
For each inter-component call: does the caller need the result immediately? If no, use async. Sync calls are coupling in disguise.
For each component and connection: what happens when it fails? Design for partial failure, not just total failure. Document: retry strategy, circuit breaker, fallback, timeout.
Define what data crosses each boundary. Avoid sharing databases between services. Define API contracts between components.
Document: the decision, the context, the alternatives considered, the rationale, and the consequences. An architecture without ADRs cannot be maintained.
Map each architecture component back to a requirement. If a component has no requirement, remove it.
"We'll start simple and scale later" Starting simple is correct. But "we'll scale later" often means "we built an architecture that cannot scale without a rewrite." Design for 10x your current load, not 1000x.
"Microservices are more scalable" Microservices are more operationally complex. Unless your team can't deploy frequently due to coupling, a monolith is simpler. Don't distribute a monolith; build a modular monolith first.
"We don't need an ADR for this" Future engineers will ask why this decision was made. ADRs cost 30 minutes. Re-learning why a decision was made costs days.
