# Architect

> Software architecture design — system architecture, monolith/microservices/serverless/event-driven trade-offs, C4 diagrams, ADRs, CQRS, hexagonal.

- Skill: `arbazkhan971/architect` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add arbazkhan971/architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arbazkhan971/architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: arbazkhan971 (https://skillmd.com/u/arbazkhan971)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arbazkhan971/architect

---


# Architect — Software Architecture Design

## Activate When
- User invokes `/godmode:architect`
- User says "design the architecture", "system architecture", "architectural design", "system design"
- User asks about monolith vs. microservices, serverless, or event-driven decisions
- When starting a greenfield project that needs structural decisions
- When `/godmode:think` identifies architecture as the primary concern
- When a system is hitting scaling, reliability, or maintainability walls

## Workflow

### Step 1: Context & Requirements Gathering
Understand the system before recommending architecture:

```
ARCHITECTURE CONTEXT:
System: <name and purpose>
Stage: <greenfield | evolving | rewrite | migration>
```

### Step 2: Architecture Pattern Evaluation
Evaluate candidate patterns against the requirements. Always evaluate at least 3 patterns:

#### Pattern Evaluation Template
For each candidate (evaluate at least 3), fill:
```
PATTERN: <Name>
├── Structure: <one-line architecture summary>
├── Strengths: <key advantages for this system>
├── Weaknesses: <key disadvantages and operational cost>
└── Best when: <conditions where this pattern wins>
```

Candidate patterns: Modular Monolith, Microservices, Serverless/FaaS, Event-Driven, CQRS, Hexagonal (Ports &
Adapters). Evaluate the top 3-6 for the system.

### Step 3: Architecture Comparison Matrix
Present a structured comparison:

```
  ARCHITECTURE COMPARISON — <system name>
```

### Step 4: C4 Architecture Diagrams
Produce diagrams at all four C4 levels for the chosen architecture:

#### Level 1: System Context
Who uses the system and what external systems does it interact with?
```
C4 CONTEXT DIAGRAM:
  Users / Actors
```

#### Level 2: Container Diagram
What are the major deployable units?
```
C4 CONTAINER DIAGRAM:
  <<System>> <System Name>
```

#### Level 3: Component Diagram
What are the major components within each container?
```
C4 COMPONENT DIAGRAM — <Container Name>:
  <<Container>> API Service
```

#### Level 4: Code Diagram
What are the key classes/modules and their relationships?
```
C4 CODE DIAGRAM — <Component>:
Show key interfaces, classes, and their relationships.
Use the codebase's actual language idioms (classes for Java/C#,
```

### Step 5: Domain-Driven Design — Strategic View
Map bounded contexts and their relationships:

```
BOUNDED CONTEXT MAP:
```

### Step 6: Quality Attribute Analysis
For the recommended architecture, analyze non-functional requirements:

```
QUALITY ATTRIBUTES:
| Attribute | How the architecture addresses it |
```

### Step 7: Architecture Decision Record
Document the decision formally:

```markdown
# ADR-<number>: <Architecture Decision Title>

## Status
```

### Step 8: Artifacts & Transition
1. Save architecture document: `docs/architecture/<system>-architecture.md`
2. Save ADR: `docs/adr/<number>-<decision>.md`
3. Save diagrams inline in the architecture document
4. Commit: `"architect: <system> — <pattern> architecture with C4 diagrams and ADR"`
5. Suggest next steps:
   - "Architecture designed. Run `/godmode:ddd` to define domain boundaries and aggregates."
   - "Architecture designed. Run `/godmode:plan` to decompose into implementation tasks."
   - "Architecture designed. Run `/godmode:api` to design the API layer."

## Key Behaviors

Never ask to continue. Loop autonomously until architecture comparison matrix, C4 diagrams, and ADR are complete.

```bash
# Analyze architecture dependencies and coupling
npx madge --circular --extensions ts src/
npx dependency-cruiser --validate .dependency-cruiser.cjs src/
```

IF team size < 5: prefer modular monolith over microservices.
WHEN afferent coupling > 10 on any module: refactor to reduce.
IF circular dependencies > 0: break cycles before adding features.

1. **Requirements before patterns.** Understand scale, team, constraints.
2. **Compare >= 3 options.** Comparison matrix forces rigor.
3. **C4 diagrams mandatory.** Minimum Level 1 + Level 2.
4. **Trade-offs are honest.** Every pattern has real downsides.
5. **ADRs capture the "why."** Reasoning, not just decision.
6. **Bounded contexts before microservices.** Map first, split second.
7. **Validate against the team.** Best arch = team can build it.

## Output Format
Print on completion:
```
ARCHITECTURE: {system_name}
Pattern: {selected_pattern} (scored {weighted_total} vs {runner_up_score} for {runner_up})
C4 diagrams: {levels_produced} levels produced
```

## TSV Logging
Log every architecture session to `.godmode/architect-results.tsv`:
```
timestamp	system	pattern_selected	patterns_compared	c4_levels	bounded_contexts	quality_attrs	adr_number	verdict
```
Append one row per session. Create the file with headers on first run.

<!-- tier-3 -->

## Quality Targets
- Target: <500ms p99 latency for critical paths
- Target: >80% code coverage on core modules
- Target: 0 circular dependencies between bounded contexts
- Max coupling: <5 imports between modules

## Success Criteria
1. At least 3 architecture patterns compared in a weighted matrix before recommendation.
2. C4 Level 1 (Context) and Level 2 (Container) diagrams produced for every session.
3. Architecture Decision Record created with Context, Decision, and Consequences sections.
4. Quality attributes table completed with specific mechanisms, not generic labels.
5. Bounded context map produced when recommending microservices or event-driven architecture.
6. Team size and operational maturity factored into the recommendation justification.
7. All artifacts committed with descriptive commit message.

## Keep/Discard Discipline
```
After EACH architecture decision:
  1. MEASURE: Score the decision against the weighted comparison matrix.
  2. COMPARE: Does the recommended pattern score highest? Are trade-offs documented honestly?
```

## Stop Conditions
```
STOP when ANY of these are true:
  - At least 3 patterns compared in weighted matrix with clear winner
  - C4 Level 1 and Level 2 diagrams produced
```

## Architecture Review Loop

Continuously audit architecture health with coupling metrics, dependency analysis, and SOLID violation detection:

```
ARCHITECTURE REVIEW LOOP:

current_iteration = 0
```

### Coupling Metrics

```
COUPLING ANALYSIS:
| Metric | Threshold | Measured | Status |
```

### Dependency Analysis

```
DEPENDENCY ANALYSIS:
| Check | Status | Details |
```

### SOLID Violation Detection

```
SOLID VIOLATION SCAN:
| Principle | Detection Signal | Count |
```

### Architecture Health Scorecard

```
ARCHITECTURE HEALTH SCORECARD:
| Dimension | Score (1-10) | Weight | Weighted |
```


## Error Recovery
| Failure | Action |
|--|--|
| Architecture decision contested | Document tradeoffs in ADR. Prototype if needed. |
| Pattern doesn't fit after start | If < 30% done: pivot. If > 30%: adapt. Document. |
| Vendor lock-in risk | Add adapter/port layer. Abstract behind interface. |
| Performance bottleneck | Profile first. Add caching/async before restructuring. |