Architect Technical Helper

A senior technical architecture agent that helps you design, document, and evaluate technical solutions, guiding decisions on system design, technology selection, and architectural trade-offs.

When to Use This Agent

Choose Architect Technical Helper when:

• Designing the architecture for a new system or major feature
• Evaluating technology choices and their trade-offs
• Creating technical design documents and architecture diagrams
• Planning migrations between architectures (monolith to microservices, on-prem to cloud)
• Making build-vs-buy decisions for system components

Consider alternatives when:

• Reviewing existing architecture for problems (use an architecture reviewer agent)
• Writing implementation code (use a development agent)
• Creating SDDs or RFCs (use an SDD helper agent)

Quick Start

Copy
# .claude/agents/architect-technical-helper.yml
name: Architect Technical Helper
description: Design and evaluate technical architectures
model: claude-sonnet
tools:
  - Read
  - Write
  - Glob
  - Grep
  - WebSearch

Example invocation:

claude "Design the architecture for a real-time collaborative document editor that supports 1000 concurrent users per document with conflict resolution"

Core Concepts

Architecture Decision Framework

Step	Question	Output
1. Requirements	What must the system do?	Functional + non-functional requirements
2. Constraints	What limits our choices?	Budget, team, timeline, compliance
3. Options	What approaches are viable?	2-3 architectural options
4. Trade-offs	What does each option sacrifice?	Trade-off matrix
5. Decision	Which option best fits constraints?	Chosen architecture + rationale
6. Validation	Does it meet requirements?	Architecture validation results

Trade-off Analysis Matrix

Copy
## Architecture Options: Real-Time Collaborative Editor

### Option A: Operational Transformation (OT)
| Dimension | Rating | Notes |
|-----------|--------|-------|
| Consistency | Strong | Proven convergence guarantees |
| Latency | Low | Transform + apply locally |
| Complexity | High | Transform functions are complex |
| Scalability | Medium | Central server bottleneck |
| Offline Support | Limited | Requires transformation log |

### Option B: CRDT (Conflict-free Replicated Data Types)
| Dimension | Rating | Notes |
|-----------|--------|-------|
| Consistency | Eventual | Mathematically guaranteed convergence |
| Latency | Very Low | Apply locally, sync async |
| Complexity | Medium | Library handles merging (Yjs, Automerge) |
| Scalability | High | Peer-to-peer capable |
| Offline Support | Full | Merge on reconnect |

### Recommendation: Option B (CRDT with Yjs)
CRDTs provide better offline support, simpler scaling, and
lower implementation complexity using mature libraries.
OT would require building complex transformation logic.

System Design Template

Copy
// High-level component architecture
interface SystemArchitecture {
  components: {
    frontend: {
      framework: 'Next.js 14';
      realtime: 'Yjs + y-websocket';
      state: 'Yjs shared types';
      auth: 'NextAuth.js';
    };
    backend: {
      api: 'Node.js + Express';
      websocket: 'y-websocket server';
      auth: 'JWT + session validation';
    };
    storage: {
      documents: 'PostgreSQL (metadata + snapshots)';
      realtime: 'Redis (presence, cursors)';
      files: 'S3 (attachments, exports)';
    };
    infrastructure: {
      compute: 'ECS Fargate (auto-scaling)';
      networking: 'ALB with WebSocket support';
      cdn: 'CloudFront (static assets)';
    };
  };
  dataFlow: string;
  scalingStrategy: string;
  failoverPlan: string;
}

Configuration

Parameter	Description	Default
detail_level	Architecture detail (overview, detailed, implementation)	detailed
diagram_format	Diagram notation (mermaid, plantuml, ascii)	mermaid
cloud_provider	Preferred cloud platform (aws, gcp, azure, agnostic)	agnostic
scale_target	Expected scale (startup, growth, enterprise)	growth
compliance	Regulatory requirements (none, soc2, hipaa, gdpr)	none
include_cost	Include cost estimation	true

Best Practices

1. Start with constraints, not solutions. The right architecture depends on team size, budget, timeline, regulatory requirements, and existing infrastructure. An architecture that is technically optimal but requires skills the-(team does not have or a budget the company cannot afford is a bad architecture. Document constraints before exploring solutions, and evaluate every option against them.

2. Present 2-3 options with explicit trade-offs, not one recommendation. Architecture decisions are rarely obvious, and presenting a single option implies there were no alternatives. Show 2-3 viable options with a trade-off matrix comparing them across relevant dimensions (cost, complexity, scalability, time-to-market, operational burden). Recommend one option with clear rationale, but let stakeholders see the full picture.

3. Design for the next order of magnitude, not the next two. A system handling 100 requests/second should be designed to handle 1,000, not 100,000. Over-designing for 1000x scale adds complexity that slows development and may never be needed. Under-designing means you will hit a wall at 2x-3x growth. One order of magnitude gives room to grow while keeping the architecture pragmatic.

4. Separate the data model decision from the infrastructure decision. Choose your data model (relational, document, graph, time-series) based on your query patterns and relationships. Choose your infrastructure (managed service, self-hosted, serverless) based on operational requirements. These are independent decisions — PostgreSQL can run on RDS, EC2, or Kubernetes, and the right hosting choice depends on your team's operational capabilities, not the data model.

5. Validate architecture with a walking skeleton before full implementation. Build the thinnest possible end-to-end implementation that touches every major component: a single API endpoint that writes to the database, publishes an event, and triggers a downstream consumer. This validates that the components connect, the deployment pipeline works, and the monitoring captures events. Invest a week in the skeleton before spending months on full implementation.

Common Issues

Architecture documents become obsolete before implementation is complete. Detailed architecture documents written months before coding drift as the team learns more during implementation. Keep architecture documents focused on decisions (the "why") rather than exhaustive specifications (the "how"). Decisions are stable; implementation details change. Link the architecture doc to the codebase so developers can see both the intent and the reality.

Technology selection is based on hype rather than fit. Teams adopt microservices, Kubernetes, or event sourcing because they are popular, not because the project needs them. Evaluate every technology choice against: "Does this solve a problem we actually have?" and "Can our team operate this?" A monolith deployed to a single server that the team can manage is better architecture than a Kubernetes cluster that no one on the team understands.

The architecture handles the happy path but not failure modes. Diagrams showing data flowing smoothly between components do not address what happens when the database is slow, the message queue is full, or a downstream service is unreachable. For every component interaction, document: What happens if it fails? What happens if it is slow? What happens if it returns unexpected data? Failure mode analysis during the design phase prevents production incidents.