Senior Architect Engine

A comprehensive skill for senior software architects covering system design, architectural decision records, technology selection, scalability patterns, and cross-cutting concerns. Provides frameworks for making and documenting high-impact technical decisions.

When to Use This Skill

Choose this skill when:

• Designing system architecture for new applications or major features
• Evaluating technology choices and documenting architectural decisions
• Planning migration strategies from monolith to microservices
• Designing for scalability, reliability, and observability
• Conducting architecture reviews and defining technical standards

Consider alternatives when:

• Need specific cloud architecture → use an AWS/GCP/Azure skill
• Working on database design specifically → use a database design skill
• Implementing CI/CD pipelines → use a DevOps skill
• Writing code for a specific framework → use that framework's skill

Quick Start

Copy
# Architecture Decision Record (ADR) Template

## ADR-001: Adopt Event-Driven Architecture for Order Processing

### Status: Accepted

### Context
Order processing currently uses synchronous REST calls between 6 services.
P99 latency is 4.2s. A single service failure cascades to order failures.

### Decision
Adopt event-driven architecture using Apache Kafka for order processing.
Services publish domain events; downstream services consume asynchronously.

### Consequences
- (+) Decoupled services, independent deployment
- (+) Natural audit trail via event log
- (+) Resilient to temporary service failures
- (-) Eventual consistency requires UI handling
- (-) Event schema evolution needs governance
- (-) Debugging distributed flows requires correlation IDs

Core Concepts

Architecture Patterns Decision Matrix

Pattern	Scalability	Complexity	Data Consistency	Best For
Monolith	Vertical	Low	Strong (ACID)	Early-stage, small teams
Modular Monolith	Vertical	Medium	Strong	Growing teams, clear domains
Microservices	Horizontal	High	Eventual	Large teams, independent deploys
Event-Driven	Horizontal	High	Eventual	Async workflows, audit trails
CQRS	Horizontal	Very High	Eventual	Read-heavy with complex queries
Serverless	Auto	Medium	Varies	Sporadic traffic, event processing

System Design Template

Copy
// System context diagram (C4 Model - Level 1)
const systemContext = {
  system: 'E-Commerce Platform',
  actors: [
    { name: 'Customer', type: 'person', interactions: ['Browse', 'Purchase', 'Track'] },
    { name: 'Admin', type: 'person', interactions: ['Manage Products', 'View Analytics'] },
  ],
  externalSystems: [
    { name: 'Payment Gateway', protocol: 'REST/HTTPS', data: 'Payment tokens' },
    { name: 'Shipping Provider', protocol: 'Webhook', data: 'Tracking updates' },
    { name: 'Email Service', protocol: 'SMTP/API', data: 'Transactional emails' },
  ],
  qualityAttributes: {
    availability: '99.95% (26 min downtime/month)',
    latency: 'p99 < 500ms for API, < 2s for pages',
    throughput: '10K orders/hour peak',
    dataRetention: '7 years for financial records',
  },
};

Scalability Patterns

Copy
// Read replica pattern for read-heavy workloads
class DatabaseRouter {
  private writer: DatabaseConnection;
  private readers: DatabaseConnection[];
  private roundRobin = 0;

  query(sql: string, params: any[], options?: { write?: boolean }) {
    if (options?.write) {
      return this.writer.query(sql, params);
    }
    // Round-robin across read replicas
    const reader = this.readers[this.roundRobin % this.readers.length];
    this.roundRobin++;
    return reader.query(sql, params);
  }
}

// Circuit breaker for external service calls
class CircuitBreaker {
  private failures = 0;
  private lastFailure = 0;
  private state: 'closed' | 'open' | 'half-open' = 'closed';

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure > this.resetTimeout) {
        this.state = 'half-open';
      } else {
        throw new Error('Circuit breaker is open');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      throw err;
    }
  }

  private onSuccess() { this.failures = 0; this.state = 'closed'; }
  private onFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    if (this.failures >= this.threshold) this.state = 'open';
  }
}

Configuration

Parameter	Type	Default	Description
adrFormat	string	'markdown'	ADR document format: markdown, MADR, or Nygard
diagramTool	string	'mermaid'	Architecture diagrams: Mermaid, PlantUML, or C4
scalabilityTarget	string	'10x'	Design for 10x current capacity
consistencyModel	string	'eventual'	Default: eventual or strong consistency
circuitBreakerThreshold	number	5	Failures before opening circuit
reviewCadence	string	'quarterly'	Architecture review frequency

Best Practices

1. Document decisions in ADRs, not meetings — Every significant architectural decision should be recorded as an Architecture Decision Record with context, options considered, decision, and consequences. Future developers need to understand why, not just what.

2. Design for 10x current load, rebuild at 100x — Over-engineering for 1000x load wastes time on problems you don't have. Design systems that handle 10x growth with configuration changes. Accept that a fundamentally different architecture may be needed at 100x.

3. Prefer boring technology for critical paths — PostgreSQL over the newest database, REST over exotic protocols, queues over complex choreography. Use novel technology where it provides clear, measurable advantages — not because it's interesting.

4. Define quality attributes with specific, measurable targets — "The system should be fast" is meaningless. "API p99 latency under 200ms at 5K requests/second" is testable. Every quality attribute needs a number, a measurement method, and a monitoring alert.

5. Make reversible decisions quickly, irreversible decisions carefully — Database technology, API contracts, and data models are expensive to change. Programming language within a service, internal class structure, and library choices are cheap. Spend your decision-making budget on the irreversible ones.

Common Issues

Microservices adopted too early cause coordination overhead — Small teams (under 10 developers) often move faster with a well-structured monolith. The overhead of service boundaries, network failures, distributed transactions, and deployment coordination outweighs independence benefits until the team and codebase grow large enough.

Architecture diagrams become outdated immediately — Static diagrams diverge from reality within weeks. Generate diagrams from code (infrastructure-as-code, dependency analysis) or embed them in ADRs tied to specific decisions. Architecture is the set of decisions, not the diagrams.

Non-functional requirements discovered in production — Performance, security, and reliability requirements must be gathered during design, not discovered during incidents. Use quality attribute scenarios in architecture reviews: "When 1000 users search simultaneously, the system should return results within 500ms."