senior-architect_skill

Overview

This skill is a senior architect toolkit for designing system architecture, creating C4 diagrams, evaluating technology trade-offs, and writing Architecture Decision Records (ADRs). It focuses on high-level design, trade-off analysis, and documentation rather than implementation or coding details. Use it to align stakeholders, capture rationale, and produce deliverables like C4 diagrams and ADRs.

How this skill works

It guides you through a structured system design process: gather requirements, produce a high-level design, and create detailed designs for APIs, data models, and error handling. The skill recommends architecture patterns (monolith vs microservices, REST vs GraphQL), database scaling strategies, and DevOps/cloud considerations. Outputs include ready-to-use ADRs, Mermaid-format C4 diagrams, API specs, and schema documentation.

When to use it

• Designing a new system or major subsystem before implementation begins
• Evaluating monolith vs microservices for team size, complexity, and scale
• Choosing between REST and GraphQL or selecting a database scaling strategy
• Creating C4 diagrams or sequence/data-flow diagrams for stakeholder communication
• Documenting architecture decisions with ADRs and migration plans

Best practices

• Start with clear functional and non-functional requirements and constraints
• Prefer a monolith to iterate quickly; extract services when scale or team structure demands
• Measure performance before optimizing and focus caching on critical paths
• Document trade-offs and alternatives in ADRs, including what is being sacrificed
• Use consistent naming, tests, and small, reviewable design increments

Example use cases

• Produce a C4 Context and Container diagram for a new SaaS product and export in Mermaid format
• Decide whether to introduce microservices for a growing product and list migration steps
• Create an ADR comparing PostgreSQL with read replicas vs sharding for a high-read workload
• Design API contracts and choose REST or GraphQL based on data complexity and client needs
• Define a deployment model using Docker, Kubernetes, and Terraform for multi-cloud environments