What is designing-architecture?

It is the practice of shaping software architecture and selecting patterns that fit the project’s size, team, and goals.

When should I use this skill?

Use it when designing systems, choosing architecture patterns, structuring projects, or deciding between monoliths and microservices.

How do I decide between monolith and microservices?

Consult the Pattern Selection Guide by project size and team size: small teams with simple needs may succeed with Layered or Monolith with clear modules; larger teams may justify Modular Monolith or Microservices if justified by scale and complexity.

designing-architecture

Scanned

npx machina-cli add skill Putra213/claude-workflow-v2/designing-architecture --openclaw

Files (1)

SKILL.md

6.6 KB

Designing Architecture

Architecture Decision Workflow

Copy this checklist and track progress:

Architecture Design Progress:
- [ ] Step 1: Understand requirements and constraints
- [ ] Step 2: Assess project size and team capabilities
- [ ] Step 3: Select architecture pattern
- [ ] Step 4: Define directory structure
- [ ] Step 5: Document trade-offs and decision
- [ ] Step 6: Validate against decision framework

Pattern Selection Guide

By Project Size

Size	Recommended Pattern
Small (<10K LOC)	Simple MVC/Layered
Medium (10K-100K)	Clean Architecture
Large (>100K)	Modular Monolith or Microservices

By Team Size

Team	Recommended
1-3 devs	Monolith with clear modules
4-10 devs	Modular Monolith
10+ devs	Microservices (if justified)

Common Patterns

1. Layered Architecture

┌─────────────────────────────┐
│       Presentation          │  ← UI, API Controllers
├─────────────────────────────┤
│       Application           │  ← Use Cases, Services
├─────────────────────────────┤
│         Domain              │  ← Business Logic, Entities
├─────────────────────────────┤
│      Infrastructure         │  ← Database, External APIs
└─────────────────────────────┘

Use when: Simple CRUD apps, small teams, quick prototypes

2. Clean Architecture

┌─────────────────────────────────────┐
│            Frameworks & Drivers      │
│  ┌─────────────────────────────┐    │
│  │     Interface Adapters       │    │
│  │  ┌─────────────────────┐    │    │
│  │  │   Application       │    │    │
│  │  │  ┌─────────────┐    │    │    │
│  │  │  │   Domain    │    │    │    │
│  │  │  └─────────────┘    │    │    │
│  │  └─────────────────────┘    │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Use when: Complex business logic, long-lived projects, testability is key

3. Hexagonal (Ports & Adapters)

        ┌──────────┐
        │ HTTP API │
        └────┬─────┘
             │ Port
    ┌────────▼────────┐
    │                 │
    │   Application   │
    │     Core        │
    │                 │
    └────────┬────────┘
             │ Port
        ┌────▼─────┐
        │ Database │
        └──────────┘

Use when: Need to swap external dependencies, multiple entry points

4. Event-Driven Architecture

Producer → Event Bus → Consumer
              │
              ├─→ Consumer
              │
              └─→ Consumer

Use when: Loose coupling needed, async processing, scalability

5. CQRS (Command Query Responsibility Segregation)

┌─────────────┐      ┌─────────────┐
│  Commands   │      │   Queries   │
│  (Write)    │      │   (Read)    │
└──────┬──────┘      └──────┬──────┘
       │                    │
       ▼                    ▼
  Write Model          Read Model
       │                    │
       └────────┬───────────┘
                ▼
           Event Store

Use when: Different read/write scaling, complex domains, event sourcing

Directory Structure Patterns

Feature-Based (Recommended for medium+)

src/
├── features/
│   ├── users/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   └── orders/
│       ├── api/
│       ├── components/
│       └── ...
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
└── app/
    └── ...

Layer-Based (Simple apps)

src/
├── controllers/
├── services/
├── models/
├── repositories/
└── utils/

Decision Framework

When making architectural decisions, evaluate against these criteria:

Simplicity - Start simple, evolve when needed
Team Skills - Match architecture to team capabilities
Requirements - Let business needs drive decisions
Scalability - Consider growth trajectory
Maintainability - Optimize for change

Trade-off Analysis Template

Use this template to document architectural decisions:

## Decision: [What we're deciding]

### Context
[Why this decision is needed now]

### Options Considered
1. Option A: [Description]
2. Option B: [Description]

### Trade-offs
| Criteria | Option A | Option B |
|----------|----------|----------|
| Complexity | Low | High |
| Scalability | Medium | High |
| Team familiarity | High | Low |

### Decision
We chose [Option] because [reasoning].

### Consequences
- [What this enables]
- [What this constrains]

Validation Checklist

After selecting an architecture, validate against:

Architecture Validation:
- [ ] Matches project size and complexity
- [ ] Aligns with team skills and experience
- [ ] Supports current requirements
- [ ] Allows for anticipated growth
- [ ] Dependencies flow inward (core has no external deps)
- [ ] Clear boundaries between modules/layers
- [ ] Testing strategy is feasible
- [ ] Trade-offs are documented

If validation fails, reconsider the pattern selection or adjust the implementation approach.

Source

git clone https://github.com/Putra213/claude-workflow-v2/blob/main/skills/designing-architecture/SKILL.mdView on GitHub

Overview

This skill guides you through designing software architecture and selecting patterns tailored to project size and team. It leverages Architecture Design Progress, Pattern Selection Guide, and common patterns to shape scalable, maintainable systems.

How This Skill Works

Start with the Architecture Design Progress checklist to understand requirements, assess project size and team capabilities, then select an architecture pattern. Define the directory structure (feature-based for medium+ or layer-based for simple apps) and document trade-offs, validating the decision against a framework before implementation.

When to Use It

Starting a new system design or refactoring an existing project.
Choosing an architecture pattern (Layered, Clean, Hexagonal, Event-Driven, CQRS) for a domain.
Defining project structure and module boundaries with team size in mind.
Evaluating trade-offs when deciding between monolith, modular monolith, and microservices.
Answering architectural approach questions for microservices versus monoliths.

Quick Start

Step 1: Understand requirements and constraints.
Step 2: Assess project size and team capabilities, then select an architecture pattern.
Step 3: Define directory structure (feature-based or layer-based) and document trade-offs; validate with the decision framework.

Best Practices

Begin with requirements and constraints and map them to the architectural decision workflow.
Document decisions and trade-offs using an Architecture Decision Record (ADR).
Align pattern choice with project size and team capabilities (as per the Pattern Selection Guide).
Prefer a Feature-Based directory structure for medium to large projects for scalability.
Revisit decisions as requirements evolve and validate against the decision framework.

Example Use Cases

Apply Layered Architecture to simple CRUD apps with small teams for quick iteration.
Use Clean Architecture for long-lived projects with complex business logic and emphasis on testability.
Adopt Hexagonal (Ports & Adapters) when you need to swap external dependencies or support multiple entry points.
Implement Event-Driven Architecture to achieve loose coupling and scalable asynchronous processing.
Leverage CQRS for domains with separate read/write scaling and potential event sourcing.

Frequently Asked Questions

Add this skill to your agents