Pro Architecture Workspace

A Claude Code skill for software architecture design, documentation, and decision-making. Covers system design, architectural patterns, trade-off analysis, Architecture Decision Records (ADRs), and system decomposition for building scalable, maintainable software systems.

When to Use This Skill

Choose Pro Architecture Workspace when:

• You're designing the architecture for a new system or service
• You need to evaluate trade-offs between architectural patterns
• You want to document architectural decisions with ADRs
• You need to decompose a monolith into services
• You're planning for scalability, reliability, or performance requirements

Consider alternatives when:

• You need C4 diagram generation (use a C4 platform skill)
• You want specific database design (use a database design skill)
• You need infrastructure/DevOps guidance (use a deployment skill)

Quick Start

Copy
# Install the skill
claude install pro-architecture-workspace

# Design a system architecture
claude "Design the architecture for a real-time collaboration app like Google Docs supporting 10K concurrent users"

# Evaluate trade-offs
claude "Should we use a monolith or microservices for our e-commerce platform? We have 5 engineers and expect to grow to 20."

# Write an ADR
claude "Write an ADR for choosing PostgreSQL over MongoDB for our user management service"

Core Concepts

Architecture Decision Framework

Step	Question	Output
Context	What problem are we solving?	Problem statement
Requirements	What are the constraints?	NFRs (latency, throughput, availability)
Options	What are the viable approaches?	2-4 architectural options
Trade-offs	What does each option sacrifice?	Comparison matrix
Decision	Which option and why?	ADR document
Consequences	What are the implications?	Follow-up actions

Common Architecture Patterns

Monolith → Single deployable unit
  ✓ Simple to develop, deploy, and debug
  ✗ Difficult to scale individual components

Microservices → Independent services per domain
  ✓ Independent scaling and deployment
  ✗ Distributed systems complexity

Event-Driven → Components communicate via events
  ✓ Loose coupling, easy to extend
  ✗ Eventual consistency, debugging difficulty

CQRS → Separate read and write models
  ✓ Optimized for read-heavy or write-heavy loads
  ✗ Increased complexity, data sync challenges

Serverless → Functions as deployment unit
  ✓ Zero ops, pay-per-use, auto-scaling
  ✗ Cold starts, vendor lock-in, limited execution time

Non-Functional Requirements Template

Category	Metric	Target
Latency	P99 response time	< 200ms
Throughput	Requests per second	10,000 RPS
Availability	Uptime percentage	99.9% (8.7h downtime/year)
Durability	Data loss tolerance	Zero data loss
Scalability	Growth handling	10x current load
Security	Compliance requirements	SOC 2, GDPR

Configuration

Parameter	Type	Default	Description
scale	string	"startup"	Scale: startup, growth, enterprise
team_size	number	5	Engineering team size
constraints	string[]	[]	Technical constraints
output_format	string	"adr"	Output: adr, diagram, analysis
cloud_provider	string	"aws"	Cloud: aws, gcp, azure, multi

Best Practices

1. Start monolith, extract services as needed — A monolith is the right architecture for most early-stage products. Extract services only when you have a clear scaling need, team boundary, or deployment independence requirement. Premature microservices create distributed monoliths.

2. Document decisions, not just designs — Architecture diagrams show what, but ADRs explain why. Future engineers need to understand the reasoning behind choices to avoid relitigating settled decisions or accidentally undermining them.

3. Design for failure — Every external dependency will fail. Design circuits breakers, fallbacks, and graceful degradation. Your architecture should specify what happens when the database is slow, the cache is cold, or a third-party API is down.

4. Make the architecture match the team — Conway's Law is real. If you have one team, a monolith is natural. If you have three teams, three services make sense. Don't fight organizational structure with technical architecture.

5. Quantify requirements before designing — "We need it to be fast" is not a requirement. "P99 latency under 200ms for search queries at 5,000 QPS" is. Vague requirements lead to over-engineered or under-engineered solutions.

Common Issues

Architecture doesn't match reality — The documented architecture and the actual system drift apart. Schedule quarterly architecture reviews and update documentation. Use dependency analysis tools to verify the actual dependency graph.

Over-engineering for scale — Building for 1 million users when you have 100 adds unnecessary complexity. Design for 10x your current load, not 1000x. You can re-architect when you have the revenue to justify it.

Microservices without the maturity — Microservices require: CI/CD per service, service discovery, distributed tracing, log aggregation, and a team experienced in distributed systems. Without these foundations, microservices create more problems than they solve.