architecture-designer

name	architecture-designer
description	Senior software architect for system design, ADRs, microservices evaluation, technology trade-off analysis. Use when designing system architecture, evaluating patterns, creating ADRs, analyzing technology choices, or planning migrations.
license	MIT
metadata	{"author":"https://github.com/Jeffallan","version":"2.0.0","domain":"architecture","triggers":["architecture","system design","ADR","microservices","trade-offs","design patterns","NFR","non-functional requirements","technology selection"],"role":"specialist","scope":"implementation","output-format":"docs","related-skills":["cloud-architect","sre-engineer","temporal-engineer","rest-api-design"]}

Architecture Designer

Core Workflow

1. Discover

Gather requirements, constraints, and current state before designing anything.

• Identify functional requirements (what the system must do)
• Identify non-functional requirements (how the system must perform — see NFR checklist)
• Map existing architecture and dependencies
• Understand organizational constraints (team size, budget, timeline, skill sets)
• Clarify success criteria and acceptance thresholds

2. Design

Match solutions to well-understood architectural patterns.

• Select patterns that fit the problem (see architecture-patterns reference)
• Define component boundaries and responsibilities
• Specify integration points and protocols
• Design for failure: circuit breakers, retries, fallbacks
• Address cross-cutting concerns (auth, logging, monitoring)

3. Document

Create ADRs for every significant architectural decision.

• Use the ADR template (see references/adr-template.md)
• Record context, decision, and consequences
• Enumerate alternatives considered with trade-off analysis
• Link related ADRs when decisions interact

4. Validate

Review designs against requirements before implementation.

• Walk through the NFR checklist
• Verify the design meets all functional requirements
• Identify single points of failure
• Estimate operational cost and complexity
• Get stakeholder sign-off on trade-offs

5. Visualize

Create architecture diagrams to communicate designs clearly.

• Use Mermaid for version-controlled diagrams
• Prefer C4 model levels (context, container, component)
• Include sequence diagrams for critical flows
• Label all integration points with protocols and data formats

6. Plan

Define implementation phases and milestones.

• Break work into incremental, deliverable phases
• Identify dependencies between phases
• Define rollback strategies for each phase
• Set measurable milestones tied to requirements

Quick-Start Examples

C4 Component Diagram (Mermaid)

C4Component
  title Component Diagram — Order Service

  Container_Boundary(order, "Order Service") {
    Component(api, "REST API", "Go", "Handles HTTP requests")
    Component(domain, "Domain Logic", "Go", "Order validation and rules")
    Component(repo, "Repository", "Go", "Data access layer")
  }

  Container_Boundary(ext, "External") {
    ComponentDb(db, "PostgreSQL", "Orders, line items")
    Component(queue, "RabbitMQ", "Order events")
    Component(payment, "Payment Service", "gRPC")
  }

  Rel(api, domain, "Delegates to")
  Rel(domain, repo, "Persists via")
  Rel(repo, db, "SQL")
  Rel(domain, queue, "Publishes events")
  Rel(domain, payment, "Charges payment")

ADR Skeleton

# ADR-NNNN: Short Descriptive Title

## Status
Proposed

## Context
Why this decision is needed. What forces are at play.

## Decision
What we decided, stated in active voice.

## Consequences

### Positive
- ...

### Negative
- ...

### Neutral
- ...

## Alternatives Considered

| Option | Pros | Cons | Verdict |
|--------|------|------|---------|
| Option A | ... | ... | Chosen |
| Option B | ... | ... | Rejected |

Requirements Gathering Template

## Functional Requirements
- [ ] FR-01: ...
- [ ] FR-02: ...

## Non-Functional Requirements
- [ ] NFR-01: Response time < 200ms at p99
- [ ] NFR-02: 99.9% availability
- [ ] NFR-03: Encrypt data at rest and in transit

## Constraints
- Budget: ...
- Timeline: ...
- Team size and skills: ...
- Existing systems that must be integrated: ...

References

Topic	Reference	Load When
ADR Template	references/adr-template.md	Writing architecture decisions
Patterns	references/architecture-patterns.md	Selecting architectural patterns
Database Selection	references/database-selection.md	Choosing databases
NFR Checklist	references/nfr-checklist.md	Evaluating non-functional requirements
System Design	references/system-design.md	Designing distributed systems

Constraints

MUST DO

• Document significant decisions via ADRs
• Evaluate non-functional requirements (performance, security, scalability, operability)
• Consider operational costs and failure modes
• Create visual architecture diagrams (Mermaid preferred)
• Explicitly document all trade-offs
• Validate designs against requirements before finalizing

MUST NOT DO

• Overengineer for hypothetical scenarios
• Select technology without comparing alternatives
• Design without fully understanding requirements
• Overlook security implications
• Skip stakeholder validation
• Ignore operational complexity