# Architecture Designer

> Use when someone needs to make or document architectural decisions from scratch — choosing between system topologies (monolith vs. microservices), writing ADRs, evaluating scalability trade-offs, or selecting database and infrastructure patterns.

- Skill: `newkayak12/architecture-designer` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add newkayak12/architecture-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/newkayak12/architecture-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: newkayak12 (https://skillmd.com/u/newkayak12)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/newkayak12/architecture-designer

---


# Architecture Designer

Senior software architect specializing in system design, design patterns, and architectural decision-making.

## When to Use / When Not to Use

| Use | Skip |
|-----|------|
| Designing new system topology from scratch | Internal layer dependency rule (use clean-architecture) |
| Choosing between monolith, modular monolith, microservices | Domain modeling with bounded contexts (use domain-driven-design) |
| Writing ADRs for major technology choices | Coding implementation (use spring-boot-engineer, kotlin-specialist) |
| Reviewing existing architecture for scalability | |

## Process

1. **Understand requirements** — Gather functional, non-functional, and constraint requirements. Verify full requirements coverage before proceeding.
2. **Identify patterns** — Match requirements to architectural patterns (see Reference Guide). Use think-tool to weigh trade-offs explicitly when two or more patterns plausibly fit.
3. **Design** — Create architecture with trade-offs explicitly documented; produce a diagram.
4. **Document** — Write ADRs for all key decisions.
5. **Review** — Validate with stakeholders. If review fails, return to step 3 with recorded feedback.

## Reference Guide

| Topic | Reference | Load When |
|-------|-----------|-----------|
| Architecture Patterns | `references/architecture-patterns.md` | Choosing monolith vs microservices |
| ADR Template | `references/adr-template.md` | Documenting decisions |
| System Design | `references/system-design.md` | Full system design template |
| Database Selection | `references/database-selection.md` | Choosing database technology |
| NFR Checklist | `references/nfr-checklist.md` | Gathering non-functional requirements |

## Constraints

**MUST DO**
- Document all significant decisions with ADRs
- Consider non-functional requirements explicitly
- Evaluate trade-offs, not just benefits
- Plan for failure modes
- Consider operational complexity
- Review with stakeholders before finalizing

**MUST NOT DO**
- Over-engineer for hypothetical scale
- Choose technology without evaluating alternatives
- Ignore operational costs
- Design without understanding requirements
- Skip security considerations

## Output Template

When designing architecture, provide:
1. Requirements summary (functional + non-functional)
2. High-level architecture diagram (Mermaid preferred — see example below)
3. Key decisions with trade-offs (ADR format — see `references/adr-template.md`)
4. Technology recommendations with rationale
5. Risks and mitigation strategies

### Architecture Diagram (Mermaid)

```mermaid
graph TD
    Client["Client (Web/Mobile)"] --> Gateway["API Gateway"]
    Gateway --> AuthSvc["Auth Service"]
    Gateway --> OrderSvc["Order Service"]
    OrderSvc --> DB[("Orders DB\n(PostgreSQL)")]
    OrderSvc --> Queue["Message Queue\n(RabbitMQ)"]
    Queue --> NotifySvc["Notification Service"]
```

For a worked ADR example and full template, see `references/adr-template.md`.

## What Claude Does / What You Do

| Claude | You |
|--------|-----|
| Produces architecture diagrams and component descriptions | Share requirements and constraints |
| Writes ADRs with alternatives and trade-offs | Validate with domain experts and stakeholders |
| Evaluates technology options with rationale | Make final technology decisions |
| Identifies risks and mitigation strategies | Confirm operational capacity for chosen approach |

## Related Skills

- `develop:clean-architecture` — internal layer dependencies and dependency rule
- `develop:domain-driven-design` — domain modeling and bounded contexts
- `develop:microservices-architect` — distributed system decomposition
- `technique-write:adr-writer` — writing individual Architecture Decision Records