AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

senior-architect

Use for system architecture decisions (monolith vs microservices, database choice, scalability, ADRs, design reviews) or architecture diagrams. Analyzes dependencies with dependency_analyzer.py, assesses the project with project_architect.py and draws Mermaid or PlantUML with architecture_diagram_generator.py.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--senior-architect at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/architecture_patterns.md

Architecture Patterns Reference

Detailed guide to software architecture patterns with trade-offs and implementation guidance.

Patterns Index

  1. Monolithic Architecture
  2. Modular Monolith
  3. Microservices Architecture
  4. Event-Driven Architecture
  5. CQRS (Command Query Responsibility Segregation)
  6. Event Sourcing
  7. Hexagonal Architecture (Ports & Adapters)
  8. Clean Architecture
  9. API Gateway Pattern

1. Monolithic Architecture

Problem it solves: Need to build and deploy a complete application as a single unit with minimal operational complexity.

When to use:

  • Small team (1-5 developers)
  • MVP or early-stage product
  • Simple domain with clear boundaries
  • Deployment simplicity is priority

When NOT to use:

  • Multiple teams need independent deployment
  • Parts of system have vastly different scaling needs
  • Technology diversity is required

Trade-offs: | Pros | Cons | |------|------| | Simple deployment | Scaling is all-or-nothing | | Easy debugging | Large codebase becomes unwieldy | | No network latency between components | Single point of failure | | Simple testing | Technology lock-in |

Structure example:

monolith/
├── src/
│   ├── controllers/    # HTTP handlers
│   ├── services/       # Business logic
│   ├── repositories/   # Data access
│   ├── models/         # Domain entities
│   └── utils/          # Shared utilities
├── tests/
└── package.json

2. Modular Monolith

Problem it solves: Need monolith simplicity but with clear boundaries that enable future extraction to services.

When to use:

  • Medium team (5-15 developers)
  • Domain boundaries are becoming clearer
  • Want option to extract services later
  • Need better code organization than traditional monolith

When NOT to use:

  • Already need independent deployment
  • Teams can't coordinate releases

Trade-offs: | Pros | Cons | |------|------| | Clear module boundaries | Still single deployment | | Easier to extract services later | Requires discipline to maintain boundaries | | Single database simplifies transactions | Can drift back to coupled monolith | | Team ownership of modules | |

Structure example:

modular-monolith/
├── modules/
│   ├── users/
│   │   ├── api/           # Public interface
│   │   ├── internal/      # Implementation
│   │   └── index.ts       # Module exports
│   ├── orders/
│   │   ├── api/
│   │   ├── internal/
│   │   └── index.ts
│   └── payments/
├── shared/                # Cross-cutting concerns
└── main.ts

Key rule: Modules communicate only through their public API, never by importing internal files.


3. Microservices Architecture

Problem it solves: Need independent deployment, scaling, and technology choices for different parts of the system.

When to use:

  • Large team (15+ developers) organized around business capabilities
  • Different parts need different scaling
  • Independent deployment is critical
  • Technology diversity is beneficial

When NOT to use:

  • Small team that can't handle operational complexity
  • Domain boundaries are unclear
  • Distributed transactions are common requirement
  • Network latency is unacceptable

Trade-offs: | Pros | Cons | |------|------| | Independent deployment | Network complexity | | Independent scaling | Distributed system challenges | | Technology flexibility | Operational overhead | | Team autonomy | Data consistency challenges | | Fault isolation | Testing complexity |

Structure example:

microservices/
├── services/
│   ├── user-service/
│   │   ├── src/
│   │   ├── Dockerfile
│   │   └── package.json
│   ├── order-service/
│   └── payment-service/
├── api-gateway/
├── infrastructure/
│   ├── kubernetes/
│   └── terraform/
└── docker-compose.yml

Communication patterns:

  • Synchronous: REST, gRPC
  • Asynchronous: Message queues (RabbitMQ, Kafka)

4. Event-Driven Architecture

Problem it solves: Need loose coupling between components that react to business events asynchronously.

When to use:

  • Components need loose coupling
  • Audit trail of all changes is valuable
  • Real-time reactions to events
  • Multiple consumers for same events

When NOT to use:

  • Simple CRUD operations
  • Synchronous responses required
  • Team unfamiliar with async patterns
  • Debugging simplicity is priority

Trade-offs: | Pros | Cons | |------|------| | Loose coupling | Eventual consistency | | Scalability | Debugging complexity | | Audit trail built-in | Message ordering challenges | | Easy to add new consumers | Infrastructure complexity |

Event structure example:

interface DomainEvent {
  eventId: string;
  eventType: string;
  aggregateId: string;
  timestamp: Date;
  payload: Record<string, unknown>;
  metadata: {
    correlationId: string;
    causationId: string;
  };
}

// Example event
const orderCreated: DomainEvent = {
  eventId: "evt-123",
  eventType: "OrderCreated",
  aggregateId: "order-456",
  timestamp: new Date(),
  payload: {
    customerId: "cust-789",
    items: [...],
    total: 99.99
  },
  metadata: {
    correlationId: "req-001",
    causationId: "cmd-create-order"
  }
};

5. CQRS

Problem it solves: Read and write workloads have different requirements and need to be optimized separately.

When to use:

  • Read/write ratio is heavily skewed (10:1 or more)
  • Read and write models differ significantly
  • Complex queries that don't map to write model
  • Different scaling needs for reads vs writes

When NOT to use:

  • Simple CRUD with balanced reads/writes
  • Read and write models are nearly identical
  • Team unfamiliar with pattern
  • Added complexity isn't justified

Trade-offs: | Pros | Cons | |------|------| | Optimized read models | Eventual consistency between models | | Independent scaling | Complexity | | Simplified queries | Synchronization logic | | Better performance | More code to maintain |

Structure example:

// Write side (Commands)
interface CreateOrderCommand {
  customerId: string;
  items: OrderItem[];
}

class OrderCommandHandler {
  async handle(cmd: CreateOrderCommand): Promise<void> {
    const order = Order.create(cmd);
    await this.repository.save(order);
    await this.eventBus.publish(order.events);
  }
}

// Read side (Queries)
interface OrderSummaryQuery {
  customerId: string;
  dateRange: DateRange;
}

class OrderQueryHandler {
  async handle(query: OrderSummaryQuery): Promise<OrderSummary[]> {
    // Query optimized read model (denormalized)
    return this.readDb.query(`
      SELECT * FROM order_summaries
      WHERE customer_id = ? AND created_at BETWEEN ? AND ?
    `, [query.customerId, query.dateRange.start, query.dateRange.end]);
  }
}

6. Event Sourcing

Problem it solves: Need complete audit trail and ability to reconstruct state at any point in time.

When to use:

  • Audit trail is regulatory requirement
  • Need to answer "how did we get here?"
  • Complex domain with undo/redo requirements
  • Debugging production issues requires history

When NOT to use:

  • Simple CRUD applications
  • No audit requirements
  • Team unfamiliar with pattern
  • Reporting on current state is primary need

Trade-offs: | Pros | Cons | |------|------| | Complete audit trail | Storage grows indefinitely | | Time-travel debugging | Query complexity | | Natural fit for event-driven | Learning curve | | Enables CQRS | Eventual consistency |

Implementation example:

// Events
type OrderEvent =
  | { type: 'OrderCreated'; customerId: string; items: Item[] }
  | { type: 'ItemAdded'; itemId: string; quantity: number }
  | { type: 'OrderShipped'; trackingNumber: string };

// Aggregate rebuilt from events
class Order {
  private state: OrderState;

  static fromEvents(events: OrderEvent[]): Order {
    const order = new Order();
    events.forEach(event => order.apply(event));
    return order;
  }

  private apply(event: OrderEvent): void {
    switch (event.type) {
      case 'OrderCreated':
        this.state = { status: 'created', items: event.items };
        break;
      case 'ItemAdded':
        this.state.items.push({ id: event.itemId, qty: event.quantity });
        break;
      case 'OrderShipped':
        this.state.status = 'shipped';
        this.state.trackingNumber = event.trackingNumber;
        break;
    }
  }
}

7. Hexagonal Architecture

Problem it solves: Need to isolate business logic from external concerns (databases, APIs, UI) for testability and flexibility.

When to use:

  • Business logic is complex and valuable
  • Multiple interfaces to same domain (API, CLI, events)
  • Testability is priority
  • External systems may change

When NOT to use:

  • Simple CRUD with no business logic
  • Single interface to domain
  • Overhead isn't justified

Trade-offs: | Pros | Cons | |------|------| | Business logic isolation | More abstractions | | Highly testable | Initial setup overhead | | External systems are swappable | Can be over-engineered | | Clear boundaries | Learning curve |

Structure example:

hexagonal/
├── domain/              # Business logic (no external deps)
│   ├── entities/
│   ├── services/
│   └── ports/           # Interfaces (what domain needs)
│       ├── OrderRepository.ts
│       └── PaymentGateway.ts
├── adapters/            # Implementations
│   ├── persistence/     # Database adapters
│   │   └── PostgresOrderRepository.ts
│   ├── payment/         # External service adapters
│   │   └── StripePaymentGateway.ts
│   └── api/             # HTTP adapters
│       └── OrderController.ts
└── config/              # Wiring it all together

8. Clean Architecture

Problem it solves: Need clear dependency rules where business logic doesn't depend on frameworks or external systems.

When to use:

  • Long-lived applications that will outlive frameworks
  • Business logic is the core value
  • Team discipline to maintain boundaries
  • Multiple delivery mechanisms (web, mobile, CLI)

When NOT to use:

  • Short-lived projects
  • Framework-centric applications
  • Simple CRUD operations

Trade-offs: | Pros | Cons | |------|------| | Framework independence | More code | | Testable business logic | Can feel over-engineered | | Clear dependency direction | Learning curve | | Flexible delivery mechanisms | Initial setup cost |

Dependency rule: Dependencies point inward. Inner circles know nothing about outer circles.

┌─────────────────────────────────────────┐
│           Frameworks & Drivers          │
│  ┌─────────────────────────────────┐    │
│  │     Interface Adapters          │    │
│  │  ┌─────────────────────────┐    │    │
│  │  │    Application Layer    │    │    │
│  │  │  ┌─────────────────┐    │    │    │
│  │  │  │    Entities     │    │    │    │
│  │  │  │ (Domain Logic)  │    │    │    │
│  │  │  └─────────────────┘    │    │    │
│  │  └─────────────────────────┘    │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

9. API Gateway Pattern

Problem it solves: Need single entry point for clients that routes to multiple backend services.

When to use:

  • Multiple backend services
  • Cross-cutting concerns (auth, rate limiting, logging)
  • Different clients need different APIs
  • Service aggregation needed

When NOT to use:

  • Single backend service
  • Simplicity is priority
  • Team can't maintain gateway

Trade-offs: | Pros | Cons | |------|------| | Single entry point | Single point of failure | | Cross-cutting concerns centralized | Additional latency | | Backend service abstraction | Complexity | | Client-specific APIs | Can become bottleneck |

Responsibilities:

┌─────────────────────────────────────┐
│            API Gateway              │
├─────────────────────────────────────┤
│ • Authentication/Authorization      │
│ • Rate limiting                     │
│ • Request/Response transformation   │
│ • Load balancing                    │
│ • Circuit breaking                  │
│ • Caching                          │
│ • Logging/Monitoring               │
└─────────────────────────────────────┘
         │         │         │
         ▼         ▼         ▼
    ┌─────┐   ┌─────┐   ┌─────┐
    │Svc A│   │Svc B│   │Svc C│
    └─────┘   └─────┘   └─────┘

Pattern Selection Quick Reference

| If you need... | Consider... | |----------------|-------------| | Simplicity, small team | Monolith | | Clear boundaries, future flexibility | Modular Monolith | | Independent deployment/scaling | Microservices | | Loose coupling, async processing | Event-Driven | | Separate read/write optimization | CQRS | | Complete audit trail | Event Sourcing | | Testable, swappable externals | Hexagonal | | Framework independence | Clean Architecture | | Single entry point, multiple services | API Gateway |