Architect Smart Helper

An autonomous agent that provides architectural guidance for building smart, intelligent systems — designing event-driven architectures, microservices patterns, and scalable system designs with practical trade-off analysis.

When to Use This Agent

Choose Architect Smart Helper when:

• You need to design the architecture for a new system or service
• Your current architecture is struggling with scale, complexity, or maintainability
• You need to evaluate microservices vs monolith or other architectural patterns
• You want trade-off analysis for technology and design decisions

Consider alternatives when:

• You need implementation help, not architecture decisions (use a developer agent)
• You need infrastructure/deployment guidance (use a DevOps agent)
• Your question is about a specific technology, not system design

Quick Start

Copy
# .claude/agents/architect-smart-helper.yml
name: architect-smart-helper
description: Design scalable, maintainable system architectures
agent_prompt: |
  You are a System Architect. When designing architectures:

  1. Understand requirements: functional, non-functional, constraints
  2. Identify bounded contexts and service boundaries
  3. Choose communication patterns (sync, async, event-driven)
  4. Design data architecture (ownership, consistency, replication)
  5. Plan for scalability, reliability, and observability
  6. Document decisions with ADRs (Architecture Decision Records)

  Design principles:
  - Start simple, evolve as needed
  - Design for failure (everything will break)
  - Data ownership drives service boundaries
  - Prefer async communication between services
  - Observe everything (metrics, logs, traces)

Example invocation:

Copy
claude "Design the architecture for a real-time collaborative document editor supporting 10K concurrent users"

Sample architecture output:

System Architecture — Collaborative Document Editor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Architecture Style: Event-Driven + CRDT

Components:
  ┌────────────┐    ┌──────────────┐    ┌─────────────┐
  │ Client SDK │◄──►│ WebSocket    │◄──►│ CRDT Engine │
  │ (Y.js)     │    │ Gateway      │    │ (Yjs)       │
  └────────────┘    │ (10K conns)  │    └──────┬──────┘
                    └──────────────┘           │
                                        ┌──────▼──────┐
                                        │ Document    │
                                        │ Storage     │
                                        │ (PostgreSQL)│
                                        └─────────────┘

Key Decisions:
  1. CRDT over OT — no central conflict resolution needed
  2. Y.js — proven CRDT library, handles 10K+ concurrent edits
  3. WebSocket with sticky sessions — connection persistence
  4. PostgreSQL — document snapshots every 100 operations
  5. Redis PubSub — cross-server operation broadcast

Scalability Plan:
  - Horizontal: Add WebSocket servers behind load balancer
  - Vertical: Each server handles 5K connections
  - Data: Shard documents across PostgreSQL nodes

Core Concepts

Architecture Decision Framework

Concern	Question	Options
Communication	Sync or async?	REST, gRPC, events, queues
Data	Shared DB or per-service?	Shared, per-service, CQRS
Consistency	Strong or eventual?	ACID, saga, event sourcing
Scaling	Vertical or horizontal?	Scale up, scale out, auto-scale
Deployment	Monolith or distributed?	Monolith, microservices, modular monolith

Architecture Decision Record (ADR)

Copy
# ADR-001: Use CRDTs for Real-Time Collaboration

## Status: Accepted

## Context
We need real-time collaborative editing for 10K concurrent users.
Two main approaches exist: Operational Transformation (OT) and CRDTs.

## Decision
Use CRDTs (specifically Y.js) for conflict resolution.

## Rationale
- CRDTs are decentralized — no single server bottleneck
- Y.js handles offline editing with automatic merge
- OT requires a central server for transformation ordering
- At 10K users, OT's central server becomes a bottleneck

## Consequences
- Higher memory usage per document (CRDT metadata)
- Team needs to learn CRDT concepts
- Undo/redo is more complex with CRDTs

Event-Driven Architecture Patterns

Copy
// Event-driven communication between services
interface DomainEvent {
  eventId: string;
  eventType: string;
  aggregateId: string;
  timestamp: Date;
  payload: Record<string, unknown>;
  metadata: { correlationId: string; causationId: string };
}

// Event publisher
class EventPublisher {
  constructor(private broker: MessageBroker) {}

  async publish(event: DomainEvent): Promise<void> {
    await this.broker.publish(event.eventType, JSON.stringify(event));
    await this.eventStore.append(event);  // Event sourcing
  }
}

// Event consumer with idempotency
class EventConsumer {
  private processedEvents = new Set<string>();

  async handle(event: DomainEvent): Promise<void> {
    if (this.processedEvents.has(event.eventId)) return;  // Idempotent
    await this.processEvent(event);
    this.processedEvents.add(event.eventId);
  }
}

Configuration

Option	Type	Default	Description
style	string	"event-driven"	Architecture style: monolith, microservices, event-driven
scaleTarget	string	"1000 rps"	Target throughput
consistencyModel	string	"eventual"	Consistency: strong, eventual, causal
generateADRs	boolean	true	Create Architecture Decision Records
includeObservability	boolean	true	Design monitoring and tracing
cloudProvider	string	"aws"	Target cloud: aws, gcp, azure

Best Practices

1. Start with a modular monolith, extract services as needed — Most projects do not need microservices on day one. A well-structured monolith with clear module boundaries is easier to develop, deploy, and debug. Extract modules into services only when you have concrete scaling or team autonomy needs.

2. Define service boundaries by data ownership — A service should own its data completely. If two services need to share a database table, they probably should not be separate services. Data ownership is the strongest signal for where to draw service boundaries.

3. Use ADRs to document every significant decision — Architecture decisions made in meetings are forgotten in weeks. Write an ADR for every decision that would be expensive to reverse: database choice, communication pattern, deployment strategy. Future developers need to understand why, not just what.

4. Design for failure at every layer — Every network call can fail. Every service can crash. Every database can go down. Implement retries with backoff, circuit breakers, graceful degradation, and health checks. Test failure scenarios with chaos engineering before they happen in production.

5. Observe everything from day one — Add structured logging, metrics (request rate, error rate, latency), and distributed tracing before you need them. When a production incident occurs, you need pre-existing observability to diagnose it. Adding observability during an incident is too late.

Common Issues

Distributed transactions across services are unreliable — A flow that creates an order and deducts inventory across two services can leave the system in an inconsistent state if one service fails. Use the saga pattern with compensating transactions instead of distributed transactions. If inventory deduction fails after order creation, the saga publishes a "cancel order" event.

Service mesh adds latency to every inter-service call — Each request between services passes through sidecar proxies, adding 2-5ms of latency per hop. For synchronous call chains (A → B → C → D), this adds 6-15ms of overhead. Minimize call chain depth, use async events where possible, and consider collapsing chatty services that always call each other into a single service.

Event ordering is lost across partitions — Events published to different partitions of a message queue may be consumed out of order. If "order created" arrives before "user registered," the order processor fails. Use partition keys (user ID, order ID) to ensure events for the same entity arrive in order, and implement event versioning with timestamps for cross-entity ordering.