@booklib/skills 1.0.0

package/microservices-patterns/references/patterns-catalog.md

@@ -0,0 +1,391 @@
+# Microservices Patterns Catalog
+
+Comprehensive reference of patterns from Chris Richardson's *Microservices Patterns*.
+Organized by problem category. Read the section relevant to the code you're generating.
+
+---
+
+## Table of Contents
+
+1. [Decomposition Patterns](#decomposition-patterns)
+2. [Communication Patterns](#communication-patterns)
+3. [API Gateway Patterns](#api-gateway-patterns)
+4. [Transaction Management — Sagas](#transaction-management--sagas)
+5. [Business Logic Patterns](#business-logic-patterns)
+6. [Event Sourcing](#event-sourcing)
+7. [Query Patterns](#query-patterns)
+8. [Testing Patterns](#testing-patterns)
+9. [Deployment Patterns](#deployment-patterns)
+10. [Observability Patterns](#observability-patterns)
+
+---
+
+## Decomposition Patterns
+
+### Decompose by Business Capability
+
+Map services to what the organization *does*. Business capabilities are stable
+over time even as org structure changes.
+
+- Identify top-level capabilities (Order Management, Delivery, Billing, etc.)
+- Each capability becomes a candidate service
+- Services own the data for their capability
+
+**When to use**: Starting a new microservices project or breaking up a monolith.
+
+### Decompose by Subdomain (DDD)
+
+Use Domain-Driven Design to identify bounded contexts. Each bounded context
+becomes a service.
+
+- Core subdomains: the competitive advantage (invest the most here)
+- Supporting subdomains: necessary but not differentiating
+- Generic subdomains: solved problems (use off-the-shelf solutions)
+
+**When to use**: Complex domain where business capability mapping isn't granular enough.
+
+### Strangler Fig Pattern
+
+Incrementally migrate from monolith to microservices by building new functionality
+as services and gradually routing traffic away from the monolith.
+
+- Stand up new service alongside monolith
+- Route specific requests to new service
+- Gradually migrate functionality
+- Eventually decommission monolith component
+
+**When to use**: Migrating an existing monolith without a big-bang rewrite.
+
+---
+
+## Communication Patterns
+
+### Synchronous — REST
+
+- Use for simple request/response interactions
+- Design APIs using the Richardson Maturity Model (ideally Level 2+)
+- Define IDL: OpenAPI/Swagger for REST
+- Handle partial failure: timeouts, retries, circuit breakers
+
+### Synchronous — gRPC
+
+- Binary protocol, strongly typed via Protocol Buffers
+- More efficient than REST for inter-service calls
+- Supports streaming (server, client, bidirectional)
+- Good for polyglot environments (code generation for many languages)
+
+### Asynchronous — Messaging
+
+- Services communicate via message broker (Kafka, RabbitMQ, etc.)
+- Message types: **Document** (carries data), **Command** (request action), **Event** (notification of change)
+- Channels: **Point-to-point** (one consumer) or **Publish-subscribe** (many consumers)
+
+Key implementation concerns:
+
+- **Message ordering**: Use partitioned channels (e.g., Kafka partitions keyed by aggregate ID)
+- **Duplicate handling**: Make consumers idempotent (track processed message IDs, or make operations naturally idempotent)
+- **Transactional outbox**: Write events to an OUTBOX table in the same transaction as business data, then relay to broker — ensures atomicity without distributed transactions
+- **Polling publisher or Transaction log tailing**: Two strategies for relaying outbox messages to the broker
+
+### Circuit Breaker
+
+Wrap remote calls in a circuit breaker to handle downstream failures gracefully:
+
+- **Closed**: Requests pass through normally
+- **Open**: Requests fail immediately (after failure threshold exceeded)
+- **Half-open**: Periodically try a request; if it succeeds, close the circuit
+
+Use libraries like Resilience4j (Java) or Polly (.NET).
+
+### Service Discovery
+
+Services need to locate each other. Two approaches:
+
+- **Client-side discovery**: Client queries a registry (e.g., Eureka) and load-balances
+- **Server-side discovery**: Client calls a router/load balancer that queries the registry (e.g., Kubernetes services, AWS ELB)
+
+---
+
+## API Gateway Patterns
+
+### API Gateway
+
+Single entry point for external clients. Responsibilities:
+
+- Request routing to appropriate microservice
+- API composition (aggregate responses from multiple services)
+- Protocol translation (external REST to internal gRPC/messaging)
+- Authentication and rate limiting
+- Edge functions (caching, monitoring, etc.)
+
+### Backend for Frontend (BFF)
+
+Separate API gateway per client type (web, mobile, third-party). Each BFF:
+
+- Tailors the API to its client's needs
+- Handles client-specific data aggregation
+- Is owned by the client team
+- Reduces coupling between client and backend service evolution
+
+**When to use BFF over single gateway**: When different clients have significantly different API needs.
+
+---
+
+## Transaction Management — Sagas
+
+### The Problem
+
+Microservices use Database per Service, so you cannot use ACID transactions
+across services. Sagas maintain data consistency using a sequence of local
+transactions with compensating transactions for rollback.
+
+### Choreography-based Saga
+
+Services publish events and subscribe to each other's events:
+
+```
+OrderService -> OrderCreated event
+  -> PaymentService listens, processes payment, publishes PaymentAuthorized
+    -> KitchenService listens, creates ticket, publishes TicketCreated
+      -> OrderService listens, approves order
+```
+
+- Pros: Simple, no central coordinator, loose coupling
+- Cons: Hard to understand the flow, cyclic dependencies possible
+
+### Orchestration-based Saga
+
+A central saga orchestrator tells participants what to do:
+
+```
+CreateOrderSaga:
+  1. OrderService.createOrder(PENDING)
+  2. PaymentService.authorize() -> fail? -> OrderService.rejectOrder()
+  3. KitchenService.createTicket() -> fail? -> PaymentService.reverseAuth(), OrderService.rejectOrder()
+  4. OrderService.approveOrder()
+```
+
+- Pros: Clear flow, easy to understand, avoids cyclic dependencies
+- Cons: Risk of centralizing too much logic in orchestrator
+
+### Saga Design Rules
+
+- Each saga step modifies one aggregate in one service
+- Every forward step needs a compensating transaction (undo/rollback action)
+- Compensating transactions must be idempotent (safe to retry)
+- Use semantic locks — mark records as "pending" during saga execution
+- Countermeasures for lack of isolation: semantic locks, commutative updates, pessimistic/optimistic views, re-reading values
+
+---
+
+## Business Logic Patterns
+
+### Aggregate Pattern (DDD)
+
+An aggregate is a cluster of domain objects treated as a unit for data changes.
+
+- **Aggregate root**: Top-level entity through which all external access occurs
+- **Invariants**: Business rules enforced within the aggregate
+- **Transaction boundary**: One transaction = one aggregate update
+- **References between aggregates**: Use IDs, not object references
+
+Design rules:
+- Keep aggregates small — reference other aggregates by identity
+- Business logic lives in the aggregate, not in service classes
+- Aggregates publish domain events when their state changes
+
+### Domain Events
+
+Events represent something meaningful that happened in the domain:
+
+- Named in past tense: OrderCreated, PaymentAuthorized, TicketAccepted
+- Contain relevant data (IDs, state at time of event)
+- Published by aggregates after state changes
+- Consumed by other services for integration
+
+### Domain Event Publishing
+
+Two approaches to reliably publish events:
+
+1. **Transactional outbox**: Store events in an outbox table in the same DB transaction as business data, then asynchronously publish to message broker
+2. **Event sourcing**: Events are the primary store (see below)
+
+---
+
+## Event Sourcing
+
+Instead of storing current state, store a sequence of state-changing events.
+Reconstruct current state by replaying events.
+
+### How It Works
+
+- Each aggregate stored as a sequence of events in an event store
+- To load: fetch all events, replay to reconstruct state
+- To save: append new events to the store
+- Event store is append-only (never update, never delete)
+
+### Benefits
+
+- Reliable event publishing (events ARE the data — no outbox needed)
+- Complete audit trail
+- Temporal queries (reconstruct state at any point in time)
+- Enables CQRS naturally
+
+### Challenges
+
+- Learning curve; different way of thinking
+- Querying the event store is hard (need CQRS for queries)
+- Event schema evolution — events are immutable, so versioning matters
+- Deleting data (e.g., GDPR) requires special handling like encryption with deletable keys
+
+### Snapshots
+
+For aggregates with many events, periodically save a snapshot of current state
+to avoid replaying the entire history. Load: last snapshot + events after snapshot.
+
+---
+
+## Query Patterns
+
+### API Composition
+
+For queries spanning multiple services, an API composer calls each service
+and combines results in memory.
+
+```
+API Composer (or API Gateway):
+  1. Call OrderService.getOrders(customerId)
+  2. Call DeliveryService.getDeliveries(orderIds)
+  3. Call RestaurantService.getRestaurants(restaurantIds)
+  4. Join results in memory, return to client
+```
+
+- Pros: Simple to implement
+- Cons: Increased latency, no efficient join/filter across services, reduced availability
+
+**When to use**: Simple queries where data from 2-3 services needs combining.
+
+### CQRS (Command Query Responsibility Segregation)
+
+Separate the write model (commands) from the read model (queries):
+
+- **Command side**: Services handle commands, publish domain events
+- **Query side**: A separate view service subscribes to events and maintains denormalized read-optimized database
+
+```
+OrderService publishes OrderCreated ->
+DeliveryService publishes DeliveryStatusUpdated ->
+  OrderHistoryViewService subscribes to both,
+  maintains denormalized OrderHistoryView table,
+  serves GET /order-history queries
+```
+
+- Pros: Efficient queries, scales reads independently, supports complex cross-service queries
+- Cons: Extra complexity, eventual consistency, additional infrastructure
+
+**When to use**: Complex queries spanning many services, or when read performance is critical.
+
+---
+
+## Testing Patterns
+
+### Consumer-Driven Contract Testing
+
+Each consumer defines a contract: "I expect your API to behave like X."
+Provider runs these contracts as tests to ensure compatibility.
+
+- Tools: Spring Cloud Contract, Pact
+- Catches breaking changes before deployment
+
+### Service Component Testing
+
+Test a service in isolation by stubbing its dependencies:
+
+- In-memory stubs for downstream services
+- In-memory or containerized database
+- Verify behavior end-to-end through the service's API
+
+### Integration Testing
+
+Test interaction between a service and its infrastructure:
+
+- Database integration tests (verify SQL, schema migrations)
+- Messaging integration tests (verify event publishing/consuming)
+- REST client integration tests (verify HTTP calls)
+- Use Docker (Testcontainers) for realistic infrastructure
+
+### Testing Pyramid for Microservices
+
+From bottom (fast, many) to top (slow, few):
+
+1. Unit tests — domain logic, aggregates, sagas
+2. Integration tests — persistence, messaging, REST clients
+3. Component tests — single service end-to-end with stubs
+4. Contract tests — API compatibility between consumer and provider
+5. End-to-end tests — full system (keep these minimal)
+
+---
+
+## Deployment Patterns
+
+### Service per Container
+
+Package each service as a Docker container image:
+
+- Encapsulates service and dependencies
+- Consistent across environments
+- Use multi-stage builds to keep images small
+
+### Kubernetes Orchestration
+
+- Deployment: Manages replicas and rolling updates
+- Service: Stable network endpoint for service discovery
+- ConfigMap/Secret: Externalized configuration
+- Probes: Liveness and readiness health checks
+
+### Service Mesh
+
+Infrastructure layer handling service-to-service communication:
+
+- Automatic mTLS between services
+- Traffic management (retries, timeouts, circuit breaking)
+- Observability (distributed tracing, metrics)
+- Tools: Istio, Linkerd
+
+### Externalized Configuration
+
+- Environment variables, config servers (Spring Cloud Config), Kubernetes ConfigMaps
+- Secrets managed separately (Vault, Kubernetes Secrets)
+- Same artifact runs in different environments
+
+---
+
+## Observability Patterns
+
+### Health Check API
+
+Every service exposes a health endpoint (GET /health) reporting:
+- Service status (UP/DOWN)
+- Dependency status (database, message broker)
+- Used by orchestrators and load balancers
+
+### Distributed Tracing
+
+Assign unique trace ID to each external request, propagate through all service calls.
+- Tools: Zipkin, Jaeger, AWS X-Ray
+- Instrument with OpenTelemetry
+
+### Log Aggregation
+
+Centralize logs from all services:
+- Include trace IDs for correlation
+- Structured logging (JSON format)
+- Tools: ELK Stack, Fluentd, Datadog
+
+### Application Metrics
+
+Collect and expose metrics from each service:
+- Request rate, latency, error rate (RED method)
+- Resource utilization
+- Business metrics
+- Tools: Prometheus + Grafana, Datadog, CloudWatch

package/microservices-patterns/references/review-checklist.md

@@ -0,0 +1,169 @@
+# Microservices Code Review Checklist
+
+Use this checklist when reviewing microservices code. Work through each section
+and flag any violations. Not every section applies to every review — skip sections
+that aren't relevant to the code under review.
+
+---
+
+## 1. Service Decomposition
+
+- [ ] Service boundaries align with business capabilities or DDD bounded contexts
+- [ ] No "god service" doing too much — each service has a focused responsibility
+- [ ] Services can be deployed independently
+- [ ] No shared domain logic libraries that couple services at the code level
+- [ ] Team ownership is clear — ideally one team owns one or a few related services
+
+**Red flags**: A service that imports domain models from another service. A change
+in one service requiring simultaneous deployment of another service.
+
+---
+
+## 2. Data Ownership
+
+- [ ] Each service has its own private database/schema
+- [ ] No shared database tables between services
+- [ ] Services never directly query another service's database
+- [ ] Data duplication (where it exists) is managed via events, not shared writes
+
+**Red flags**: SQL joins across tables owned by different services. Connection strings
+pointing to another service's database. Multiple services with write access to the same table.
+
+---
+
+## 3. Inter-Service Communication
+
+- [ ] Communication style (sync vs async) matches the use case
+- [ ] Synchronous calls have timeouts configured
+- [ ] Circuit breakers protect against cascading failures
+- [ ] No long synchronous call chains (A -> B -> C -> D)
+- [ ] Async messaging uses transactional outbox or event sourcing for reliability
+- [ ] Message consumers are idempotent
+- [ ] Service discovery is in place (not hardcoded URLs)
+
+**Red flags**: HTTP calls without timeouts. Retry loops without backoff. Direct
+database writes as a "faster alternative" to messaging.
+
+---
+
+## 4. API Design
+
+- [ ] APIs are versioned or use backward-compatible evolution
+- [ ] API contracts are defined (OpenAPI, Proto files, AsyncAPI)
+- [ ] Error responses follow a consistent format
+- [ ] APIs return only what the client needs (no over-fetching)
+- [ ] Consumer-driven contract tests exist for key API consumers
+
+**Red flags**: Breaking API changes without versioning. No API documentation or contract.
+Internal implementation details leaking through the API.
+
+---
+
+## 5. Transaction Management (Sagas)
+
+- [ ] Cross-service operations use sagas, not distributed transactions (no 2PC)
+- [ ] Each saga step has a compensating transaction defined
+- [ ] Compensating transactions are idempotent
+- [ ] Saga state is persisted (not just in-memory)
+- [ ] Semantic locks or other countermeasures handle isolation concerns
+- [ ] Saga orchestrator (if used) doesn't contain business logic — only coordinates
+
+**Red flags**: Try/catch blocks attempting to rollback across service boundaries without
+a saga. Services directly calling another service's "undo" endpoint without saga coordination.
+Missing compensating transactions.
+
+---
+
+## 6. Business Logic & Domain Model
+
+- [ ] Business logic lives in domain objects (aggregates), not in service/controller classes
+- [ ] Aggregates enforce their own invariants
+- [ ] One transaction modifies exactly one aggregate
+- [ ] Aggregates reference other aggregates by ID, not by object reference
+- [ ] Domain events are published after aggregate state changes
+- [ ] Value objects are used where identity isn't needed
+
+**Red flags**: Anemic domain model (entities are just data holders, all logic in services).
+Transactions that modify multiple aggregates. Direct object references between aggregates.
+
+---
+
+## 7. Event Handling
+
+- [ ] Events are named in past tense (OrderCreated, not CreateOrder)
+- [ ] Events contain sufficient data for consumers to act without callbacks
+- [ ] Event schema versioning strategy exists
+- [ ] Event handlers are idempotent
+- [ ] Ordering is preserved where needed (partition by aggregate ID)
+- [ ] If using event sourcing: snapshots exist for aggregates with many events
+
+**Red flags**: Events named as commands. Event handlers that call back to the
+publishing service for more data. No strategy for event schema evolution.
+
+---
+
+## 8. Query Implementation
+
+- [ ] Cross-service queries use API Composition or CQRS — not direct DB access
+- [ ] API Composition: composer handles partial failures gracefully
+- [ ] CQRS views: event handlers maintain denormalized read models
+- [ ] CQRS views: eventual consistency is acceptable for the use case
+- [ ] Query performance is adequate for the access patterns
+
+**Red flags**: Queries that join data from multiple services' databases. N+1 query
+patterns in API composition. CQRS view that falls too far behind event stream.
+
+---
+
+## 9. Testing
+
+- [ ] Unit tests cover domain logic (aggregates, value objects, saga orchestrators)
+- [ ] Integration tests verify infrastructure interactions (DB, messaging, HTTP clients)
+- [ ] Component tests exercise the service end-to-end with stubbed dependencies
+- [ ] Consumer-driven contract tests protect API compatibility
+- [ ] End-to-end tests are minimal and focused on critical paths
+- [ ] Tests use containers (Testcontainers) for realistic infrastructure testing
+
+**Red flags**: Only end-to-end tests (slow, brittle). No contract tests between
+services that communicate. Mocks that hide real integration issues.
+
+---
+
+## 10. Observability
+
+- [ ] Health check endpoint exists (GET /health or /actuator/health)
+- [ ] Structured logging with correlation/trace IDs
+- [ ] Distributed tracing is instrumented (OpenTelemetry or equivalent)
+- [ ] Key metrics are exposed (request rate, latency, error rate)
+- [ ] Alerts are configured for critical failure conditions
+
+**Red flags**: Console.log as the only logging. No health endpoint. No way to
+trace a request across service boundaries.
+
+---
+
+## 11. Configuration & Security
+
+- [ ] Configuration is externalized (not hardcoded)
+- [ ] Secrets are managed securely (not in source code or env files in repo)
+- [ ] Service-to-service communication is authenticated (mTLS or API keys)
+- [ ] Input validation exists at service boundaries
+- [ ] Principle of least privilege for database access
+
+**Red flags**: Database passwords in source code. Services accepting unauthenticated
+internal requests. Configuration values baked into artifacts.
+
+---
+
+## Severity Classification
+
+When reporting issues, classify them:
+
+- **Critical**: Data loss risk, security vulnerability, or correctness issue
+  (e.g., shared database, missing compensating transactions, no auth)
+- **Major**: Architectural debt that will cause scaling/maintenance problems
+  (e.g., synchronous chains, god service, anemic domain model)
+- **Minor**: Best practice deviation with limited immediate impact
+  (e.g., missing health check, no structured logging)
+- **Suggestion**: Improvement that would be nice but isn't urgent
+  (e.g., could benefit from CQRS in the future, consider event sourcing)

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@booklib/skills",
+  "version": "1.0.0",
+  "description": "Book knowledge distilled into structured AI skills for Claude Code and other AI assistants",
+  "bin": {
+    "skills": "./bin/skills.js"
+  },
+  "keywords": ["claude", "claude-code", "ai", "skills", "agent-skills"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agent-skills/skills.git"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}