Skip to main content
skill CX Codex

architecture-patterns · miles990 — Claude Code skill: what it does

architecture-patterns guides system design choices across monolithic, microservices, event-driven, serverless, and clean architectures.

MIT 282 installs ★ 26 updated 2026-01-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add miles990/claude-software-skills --skill architecture-patterns -a claude-code
Open on GitHub

What architecture-patterns does

This skill equips coding agents with structured architectural guidance. It includes concrete decision rules based on constraints such as team size, operational overhead, and domain complexity. The knowledge base covers clean architecture layers, hexagonal ports and adapters, and tactical domain-driven design.

Specific operational limits are detailed directly in the reference, such as serverless function timeouts of 15 to 30 minutes and cold start penalties from 100ms to 2 seconds. It also flags anti-patterns, specifically distributed monoliths and database sharing across decoupled microservices.

What it helps with

  • select appropriate architecture based on team size and domain boundaries
  • organize directory layouts following clean or modular monolithic structures
  • define bounded contexts and aggregates using domain-driven design
  • mitigate common pitfalls like shared microservice databases

Example prompts for the agent

  • Suggest a module directory layout for a modular monolithic application
  • Design an event-sourced order processing flow using CQRS
  • Outline driving adapters and input ports for a hexagonal setup

How to install architecture-patterns

1Skills CLI (Vercel)

npx skills add miles990/claude-software-skills --skill architecture-patterns -a claude-code

2Manually: put the files in place

~/.claude/skills/architecture-patterns/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/architecture-patterns/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about architecture-patterns

How to install architecture-patterns in Claude Code?

Run npx skills add miles990/claude-software-skills --skill architecture-patterns -a claude-code in your terminal.

What does architecture-patterns do?

It guides software design decisions by providing trade-off evaluations, layer diagrams, and rules for monoliths, microservices, and DDD.

When does the skill recommend starting with a monolith?

The embedded decision tree points to a monolith for startups, MVP stages, simple domain logic, and teams with fewer than 10 developers.

Source text

SKILL.md · MIT
---
name: architecture-patterns
description: Software architecture patterns and best practices
domain: software-design
version: 1.0.0
tags: [architecture, microservices, monolithic, event-driven, serverless, ddd]
triggers:
  keywords:
    primary: [architecture, microservices, monolith, serverless, event-driven, ddd]
    secondary: [hexagonal, clean architecture, cqrs, saga, domain driven, modular]
  context_boost: [design, structure, enterprise, scale]
  context_penalty: [frontend, css, ui]
  priority: high
---

# Architecture Patterns

## Overview

Architecture patterns provide proven solutions for structuring software systems. Choosing the right architecture is crucial for scalability, maintainability, and team productivity.

## Patterns

### Monolithic Architecture

**Description**: Single deployable unit containing all application functionality.

**Key Features**:
- Simple deployment and development
- Shared database and memory
- Straightforward debugging

**Use Cases**:
- MVPs and startups
- Small teams (< 10 developers)
- Simple domain logic

**Best Practices**:
```
src/
├── modules/          # Feature-based organization
│   ├── users/
│   ├── orders/
│   └── products/
├── shared/           # Cross-cutting concerns
└── infrastructure/   # External services
```

---

### Microservices Architecture

**Description**: Distributed system of independently deployable services.

**Key Features**:
- Independent deployment and scaling
- Technology diversity per service
- Fault isolation

**Use Cases**:
- Large teams needing autonomy
- Complex domains with clear boundaries
- High scalability requirements

**Key Components**:
| Component | Purpose | Tools |
|-----------|---------|-------|
| API Gateway | Entry point, routing | Kong, AWS API Gateway |
| Service Discovery | Service registration | Consul, Kubernetes DNS |
| Config Management | Centralized config | Spring Cloud Config, Consul |
| Circuit Breaker | Fault tolerance | Resilience4j, Hystrix |

**Best Practices**:
1. Design around business capabilities
2. Decentralize data management
3. Design for failure
4. Automate deployment

---

### Event-Driven Architecture

**Description**: Systems communicating through events.

**Key Patterns**:

| Pattern | Description | Use Case |
|---------|-------------|----------|
| Event Sourcing | Store state as events | Audit trails, temporal queries |
| CQRS | Separate read/write models | High-read workloads |
| Saga | Distributed transactions | Cross-service workflows |

**Event Sourcing Example**:
```typescript
// Events are the source of truth
interface OrderEvent {
  id: string;
  type: 'OrderCreated' | 'ItemAdded' | 'OrderShipped';
  timestamp: Date;
  payload: unknown;
}

// Rebuild state from events
function rebuildOrder(events: OrderEvent[]): Order {
  return events.reduce((order, event) => {
    switch (event.type) {
      case 'OrderCreated': return { ...event.payload };
      case 'ItemAdded': return { ...order, items: [...order.items, event.payload] };
      case 'OrderShipped': return { ...order, status: 'shipped' };
    }
  }, {} as Order);
}
```

---

### Serverless Architecture

**Description**: Cloud-managed execution without server management.

**Key Features**:
- Pay-per-execution pricing
- Auto-scaling to zero
- Reduced operational overhead

**Considerations**:
| Aspect | Impact |
|--------|--------|
| Cold Start | 100ms-2s latency on first invocation |
| Timeout | Usually 15-30 min max execution |
| State | Must use external storage |
| Vendor Lock-in | Platform-specific features |

**Best Practices**:
1. Keep functions small and focused
2. Minimize dependencies
3. Use connection pooling for databases
4. Implement proper error handling

---

### Clean Architecture

**Description**: Dependency-inverted architecture with domain at center.

**Layer Structure**:
```
┌──────────────────────────────────────┐
│           Frameworks & Drivers       │  ← External (DB, Web, UI)
├──────────────────────────────────────┤
│           Interface Adapters         │  ← Controllers, Gateways
├──────────────────────────────────────┤
│           Application Business       │  ← Use Cases
├──────────────────────────────────────┤
│           Enterprise Business        │  ← Entities, Domain Rules
└──────────────────────────────────────┘
```

**Dependency Rule**: Dependencies point inward. Inner layers know nothing about outer layers.

---

### Domain-Driven Design (DDD)

**Description**: Architecture aligned with business domain.

**Strategic Patterns**:
| Pattern | Purpose |
|---------|---------|
| Bounded Context | Clear domain boundaries |
| Context Map | Relationships between contexts |
| Ubiquitous Language | Shared vocabulary |

**Tactical Patterns**:
| Pattern | Purpose |
|---------|---------|
| Entity | Objects with identity |
| Value Object | Immutable descriptors |
| Aggregate | Consistency boundary |
| Repository | Collection-like persistence |
| Domain Event | Something that happened |

---

## Decision Guide

```
START
  │
  ├─ Team size < 10? ──────────────────→ Monolith
  │
  ├─ Need independent deployments? ────→ Microservices
  │
  ├─ Audit trail required? ────────────→ Event Sourcing
  │
  ├─ Variable/unpredictable load? ─────→ Serverless
  │
  ├─ Complex business logic? ──────────→ Clean Architecture + DDD
  │
  └─ Default ──────────────────────────→ Modular Monolith
```

## Common Pitfalls

### 1. Premature Microservices
**Problem**: Starting with microservices for a simple application
**Solution**: Start monolithic, extract services when boundaries are clear

### 2. Distributed Monolith
**Problem**: Microservices that must deploy together
**Solution**: Ensure services are truly independent with clear API contracts

### 3. Ignoring Data Boundaries
**Problem**: Shared database across services
**Solution**: Each service owns its data, use events for synchronization

---

### Hexagonal Architecture (Ports & Adapters)

**Description**: Application core isolated from external concerns through ports (interfaces) and adapters (implementations).

**Structure**:
```
┌─────────────────────────────────────────────────────────────┐
│                      Driving Adapters                       │
│    (REST API, CLI, GraphQL, Message Consumer)               │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                    Input Ports                              │
│              (Use Case Interfaces)                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                   APPLICATION CORE                          │
│              (Domain Logic, Entities)                       │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                   Output Ports                              │
│           (Repository, Gateway Interfaces)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                     Driven Adapters                         │
│    (Database, External APIs, Message Publisher)             │
└─────────────────────────────────────────────────────────────┘
```

**TypeScript Example**:
```typescript
// Port (Interface)
interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// Adapter (Implementation)
class PostgresOrderRepository implements OrderRepository {
  constructor(private db: Database) {}

  async save(order: Order): Promise<void> {
    await this.db.query('INSERT INTO orders...', [order]);
  }

  async findById(id: string): Promise<Order | null> {
    const row = await this.db.query('SELECT * FROM orders WHERE id = $1', [id]);
    return row ? this.toDomain(row) : null;
  }
}

// Use Case (Application Core)
class CreateOrderUseCase {
  constructor(private orderRepo: OrderRepository) {} // Depends on Port, not Adapter

  async execute(input: CreateOrderInput): Promise<Order> {
    const order = new Order(input);
    await this.orderRepo.save(order);
    return order;
  }
}
```

**Benefits**:
- Easy to swap implementations (DB, external services)
- Highly testable (mock ports)
- Framework-agnostic domain logic

---

### Modular Monolith

**Description**: Monolith with strict module boundaries, preparing for potential microservices extraction.

**Key Features**:
- Modules communicate via defined interfaces
- Each module owns its data
- Can be deployed as single unit or extracted

**Structure**:
```
src/
├── modules/
│   ├── users/
│   │   ├── api/           # Public API of module
│   │   │   └── UserService.ts
│   │   ├── internal/      # Private implementation
│   │   │   ├── UserRepository.ts
│   │   │   └── UserEntity.ts
│   │   └── index.ts       # Only exports public API
│   ├── orders/
│   │   ├── api/
│   │   │   └── OrderService.ts
│   │   ├── internal/
│   │   └── index.ts
│   └── shared/            # Cross-cutting utilities
├── infrastructure/
│   ├── database/
│   ├── messaging/
│   └── http/
└── main.ts
```

**Module Communication Rules**:
```typescript
// ✅ Good: Use public API
import { UserService } from '@modules/users';
const user = await userService.getById(id);

// ❌ Bad: Direct access to internal
import { UserRepository } from '@modules/users/internal/UserRepository';
```

**Enforcement**:
```json
// eslint rules or ts-paths to prevent internal imports
{
  "rules": {
    "no-restricted-imports": ["error", {
      "patterns": ["@modules/*/internal/*"]
    }]
  }
}
```

---

### Strangler Fig Pattern

**Description**: Gradually replace legacy system by routing traffic to new implementation.

**Migration Process**:
```
Phase 1: Facade
┌─────────┐     ┌─────────┐     ┌─────────────┐
│ Client  │────→│ Facade  │────→│ Legacy      │
└─────────┘     └─────────┘     │ System      │
                                └─────────────┘

Phase 2: Partial Migration
┌─────────┐     ┌─────────┐     ┌─────────────┐
│ Client  │────→│ Facade  │──┬─→│ Legacy      │
└─────────┘     └─────────┘  │  └─────────────┘
                             │  ┌─────────────┐
                             └─→│ New System  │
                                └─────────────┘

Phase 3: Complete Migration
┌─────────┐     ┌─────────┐     ┌─────────────┐
│ Client  │────→│ Facade  │────→│ New System  │
└─────────┘     └─────────┘     └─────────────┘
```

**Implementation**:
```typescript
class PaymentFacade {
  constructor(
    private legacyPayment: LegacyPaymentService,
    private newPayment: NewPaymentService,
    private featureFlags: FeatureFlags
  ) {}

  async processPayment(payment: Payment): Promise<Result> {
    // Gradually migrate traffic
    if (this.featureFlags.isEnabled('new-payment-system', payment.userId)) {
      return this.newPayment.process(payment);
    }
    return this.legacyPayment.process(payment);
  }
}
```

---

### Backend for Frontend (BFF)

**Description**: Dedicated backend for each frontend type (web, mobile, etc.).

**Structure**:
```
                    ┌─────────────┐
                    │ Web Client  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │  Web BFF    │
                    └──────┬──────┘
                           │
       ┌───────────────────┼───────────────────┐
       │                   │                   │
┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐
│ User Service│    │Order Service│    │Product Svc  │
└─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │
       └───────────────────┼───────────────────┘
                           │
                    ┌──────▼──────┐
                    │ Mobile BFF  │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │Mobile Client│
                    └─────────────┘
```

**Benefits**:
- Optimized payload for each client
- Client-specific authentication
- Independent deployment per frontend
- Reduces over-fetching

**When to Use**:
| Scenario | Recommendation |
|----------|----------------|
| Single client type | Skip BFF |
| Web + Mobile with same needs | Single API Gateway |
| Different UX per platform | Separate BFFs |
| Multiple teams per frontend | Dedicated BFFs |

---

## Architecture Patterns Comparison

| Pattern | Complexity | Scalability | Team Size | Best For |
|---------|------------|-------------|-----------|----------|
| Monolith | Low | Vertical | Small (2-10) | MVPs, Simple apps |
| Modular Monolith | Medium | Vertical | Medium (5-20) | Growing apps |
| Microservices | High | Horizontal | Large (20+) | Complex domains |
| Serverless | Medium | Auto | Any | Event-driven, Variable load |
| Event-Driven | High | Horizontal | Medium-Large | Async workflows |

---

## Architecture Decision Record (ADR) Template

When choosing an architecture, document decisions:

```markdown
# ADR-001: Choose Modular Monolith

## Status
Accepted

## Context
- Team of 8 developers
- MVP deadline in 3 months
- Uncertain about domain boundaries
- Limited DevOps resources

## Decision
Adopt Modular Monolith with strict boundaries

## Consequences
### Positive
- Faster initial development
- Simpler deployment
- Can extract services later

### Negative
- Single point of failure
- Scaling limited to vertical
- Need discipline for module boundaries

## Alternatives Considered
1. Microservices - Too complex for team size
2. Traditional Monolith - No path to scale
```

---

## Evolution Path

```
┌─────────────────────────────────────────────────────────────────┐
│                    Architecture Evolution                        │
│                                                                 │
│   Monolith ──→ Modular Monolith ──→ Microservices              │
│      │              │                     │                     │
│      │              │                     ▼                     │
│      │              │            Event-Driven / CQRS            │
│      │              │                     │                     │
│      ▼              ▼                     ▼                     │
│  [Simple]     [Growing]            [Complex/Scale]              │
│                                                                 │
│   Tip: Don't skip steps. Each stage teaches domain boundaries. │
└─────────────────────────────────────────────────────────────────┘
```

---

## Anti-Patterns to Avoid

### 1. Big Ball of Mud
**Symptom**: No clear structure, everything depends on everything
**Fix**: Introduce module boundaries, apply Clean Architecture principles

### 2. Golden Hammer
**Symptom**: Using same architecture for every project
**Fix**: Evaluate requirements, use decision guide

### 3. Accidental Complexity
**Symptom**: Architecture more complex than domain requires
**Fix**: Start simple, add complexity only when needed

### 4. Resume-Driven Development
**Symptom**: Choosing tech for learning, not solving problems
**Fix**: Align architecture with team skills and project needs

### 5. Vendor Lock-In
**Symptom**: Core logic tightly coupled to cloud provider
**Fix**: Use Hexagonal Architecture, abstract vendor-specific code

---

## Performance Considerations by Pattern

| Pattern | Latency | Throughput | Cold Start |
|---------|---------|------------|------------|
| Monolith | Low | High | N/A |
| Microservices | Medium (network) | High (distributed) | N/A |
| Serverless | Variable | Auto-scale | 100ms-2s |
| Event-Driven | Higher (async) | Very High | Depends |

---

## Testing Strategies by Pattern

### Monolith
```
Unit Tests → Integration Tests → E2E Tests
    70%           20%              10%
```

### Microservices
```
Unit Tests → Contract Tests → Integration → E2E
    60%           20%           15%         5%

// Contract Test Example (Pact)
const provider = new Pact({ consumer: 'OrderService', provider: 'UserService' });
await provider.addInteraction({
  state: 'user exists',
  uponReceiving: 'get user request',
  withRequest: { method: 'GET', path: '/users/123' },
  willRespondWith: { status: 200, body: { id: '123', name: 'John' } }
});
```

### Event-Driven
- Test event producers and consumers independently
- Use event schema validation
- Test saga/workflow orchestration

---

## Related Skills

- [[api-design]] - API design for service communication
- [[system-design]] - Large-scale system considerations
- [[devops-cicd]] - Deployment strategies for each pattern
- [[data-design]] - Database patterns for each architecture

© miles990 · MIT · miles990/claude-software-skills

Similar skills

All skills for Backend and APIs →

architecture-patterns by other authors comes first.

architecture-patterns Seth Hobson architecture-patterns guides backend architecture with Clean Architecture, Hexagonal Architecture, and DDD. Use it when designing a service, untangling a monolith, or tracing dependency cycles. CX Codex +1 24,144installs architecture-patterns OrchestKit architecture-patterns enforces clean architecture, backend layer boundaries, and directory limits. Triggers when designing module boundaries or running refactoring tasks. CX Codex +1 236installs enterprise-architecture-patterns manutej enterprise-architecture-patterns is a Claude Code skill with architecture-pattern references for designing microservices. CX Codex +1 530installs microservices-architecture travisjneuman The microservices-architecture Claude Code skill guides microservice design, monolith decomposition, and service communication choices. It activates for distributed-system design tasks. CX Codex +1 153installs spring-boot-event-driven-patterns giuseppe-trisciuoglio spring-boot-event-driven-patterns is a Claude Code skill for Spring Boot 3.x that replaces synchronous service calls with events using domain events, Kafka and the transactional outbox. CX Codex +1 4,000installs architect-review rmyndharis architect-review — a skill for Claude Code, Codex, Cursor, and other tools. Evaluates system architecture, scalability impacts, and distributed design patterns during major refactoring. CX Codex +1 154installs catalog-documentation-creator eventcatalog catalog-documentation-creator generates EventCatalog documentation files for services, events, ADRs, and domains with valid YAML frontmatter. Works from prompts or scans existing codebases. CX Codex +1 1,400installs domain-model-boundaries-mapper patricio0312rev domain-model-boundaries-mapper maps domain areas, module ownership, dependencies, and interfaces in a codebase. Useful when untangling a monolith or planning a domain-driven redesign. CX Codex +1 270installs

From the same set13

The whole set →
game-development game-development — a skill with game architecture patterns: game loop, ECS, collision detection, enemy AI. Useful when the agent writes logic for Unity, Godot or Flutter. CX Codex +1 417installs project-management project-management supplies AI coding assistants with Scrum and Kanban frameworks, user story guidelines, and issue templates for GitHub or Linear. CX Codex +1 399installs e-commerce e-commerce — a skill for building online stores: cart state, Stripe payments, checkout and inventory. Useful when you wire up a checkout or add payment processing. CX Codex +1 377installs saas-platforms saas-platforms — a coding skill that walks your agent through multi-tenancy, subscription billing and usage tracking for a SaaS app. CX Codex +1 364installs developer-tools developer-tools guides AI coding assistants in building Node.js command-line tools and typed API client SDKs. CX Codex +1 218installs frontend Frontend patterns and best practices for React, Vue, and Next.js. Guides code generation for components, state stores, and custom hooks. CX Codex +1 194installs automation-scripts automation-scripts is a Claude Code skill for building automation scripts and task runners. It activates for requests about Makefiles, npm scripts, and development workflows. CX Codex +1 152installs git-workflows git-workflows is a Claude Code skill with recipes for branching, daily Git commands, undo steps, and commit hooks. The agent reads them from one skill file. CX Codex +1 114installs

Project sponsors

Companies that keep this analytics open