@corbat-tech/coding-standards-mcp 1.0.0

package/standards/architecture/ddd.md

@@ -0,0 +1,173 @@
+# Domain-Driven Design (DDD)
+
+## Overview
+
+Domain-Driven Design is an approach to software development that centers the development on the core business domain. It provides tactical and strategic patterns for modeling complex domains.
+
+## Tactical Patterns
+
+### Entities
+
+Objects with a unique identity that persists over time:
+
+```java
+public class Order {
+    private final OrderId id;  // Unique identity
+    private OrderStatus status;
+    private List<OrderLine> lines;
+
+    // Identity-based equality
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof Order order)) return false;
+        return id.equals(order.id);
+    }
+}
+```
+
+**Rules:**
+- Must have a unique identifier
+- Equality based on identity, not attributes
+- Can change state over time
+- Protect invariants
+
+### Value Objects
+
+Immutable objects defined by their attributes:
+
+```java
+public record Money(BigDecimal amount, Currency currency) {
+    public Money {
+        if (amount == null || amount.compareTo(BigDecimal.ZERO) < 0) {
+            throw new IllegalArgumentException("Amount must be non-negative");
+        }
+        Objects.requireNonNull(currency);
+    }
+
+    public Money add(Money other) {
+        if (!currency.equals(other.currency)) {
+            throw new IllegalArgumentException("Cannot add different currencies");
+        }
+        return new Money(amount.add(other.amount), currency);
+    }
+}
+```
+
+**Rules:**
+- Immutable (use Java records when possible)
+- Equality based on all attributes
+- Self-validating
+- No identity
+
+### Aggregates
+
+A cluster of entities and value objects with a root entity:
+
+```java
+public class Order {  // Aggregate Root
+    private final OrderId id;
+    private final CustomerId customerId;
+    private List<OrderLine> lines;  // Part of aggregate
+    private OrderStatus status;
+
+    public void addLine(Product product, int quantity) {
+        // Invariant protection
+        if (status != OrderStatus.DRAFT) {
+            throw new IllegalStateException("Cannot modify confirmed order");
+        }
+        lines.add(new OrderLine(product.getId(), quantity, product.getPrice()));
+    }
+}
+```
+
+**Rules:**
+- Access only through the root
+- Root enforces invariants
+- Transactional consistency boundary
+- Reference other aggregates by ID only
+
+### Domain Events
+
+Record of something that happened in the domain:
+
+```java
+public record OrderPlaced(
+    OrderId orderId,
+    CustomerId customerId,
+    Money totalAmount,
+    Instant occurredAt
+) implements DomainEvent {
+    public OrderPlaced {
+        Objects.requireNonNull(orderId);
+        Objects.requireNonNull(customerId);
+        Objects.requireNonNull(totalAmount);
+        occurredAt = occurredAt != null ? occurredAt : Instant.now();
+    }
+}
+```
+
+**Rules:**
+- Immutable
+- Named in past tense
+- Contain all relevant data
+- Published after state change
+
+### Repositories
+
+Collection-like interface for aggregate persistence:
+
+```java
+public interface OrderRepository {
+    Optional<Order> findById(OrderId id);
+    void save(Order order);
+    void delete(Order order);
+    List<Order> findByCustomerId(CustomerId customerId);
+}
+```
+
+**Rules:**
+- One repository per aggregate
+- Interface in domain, implementation in infrastructure
+- Return domain objects, not DTOs
+
+### Domain Services
+
+Stateless operations that don't belong to entities:
+
+```java
+public class PricingService {
+    public Money calculateDiscount(Order order, Customer customer) {
+        // Complex calculation involving multiple aggregates
+    }
+}
+```
+
+**Rules:**
+- Stateless
+- Named after domain operations
+- Use when logic doesn't fit in entities
+
+## Strategic Patterns
+
+### Bounded Contexts
+
+Explicit boundaries where a domain model is defined and applicable:
+- Each context has its own ubiquitous language
+- Models can differ between contexts
+- Define clear interfaces between contexts
+
+### Ubiquitous Language
+
+A shared language between developers and domain experts:
+- Use domain terms in code
+- Class names = domain concepts
+- Method names = domain operations
+- Avoid technical jargon in domain layer
+
+## Anti-Patterns to Avoid
+
+1. **Anemic Domain Model**: Entities with only getters/setters, logic in services
+2. **God Aggregate**: Too large aggregates with too many entities
+3. **Aggregate Reference by Object**: Referencing other aggregates by object instead of ID
+4. **Repository in Entity**: Entities accessing repositories directly

package/standards/architecture/hexagonal.md

@@ -0,0 +1,97 @@
+# Hexagonal Architecture (Ports & Adapters)
+
+## Overview
+
+Hexagonal Architecture, also known as Ports & Adapters, isolates the core business logic from external concerns. The application core is at the center, surrounded by ports (interfaces) and adapters (implementations).
+
+## Structure
+
+```
+src/
+├── domain/           # Core business logic (innermost)
+│   ├── entities/     # Business entities
+│   ├── value-objects/# Immutable value objects
+│   ├── events/       # Domain events
+│   └── ports/        # Interfaces (input & output)
+├── application/      # Use cases (middle layer)
+│   ├── use-cases/    # Application use cases
+│   └── services/     # Application services
+└── infrastructure/   # External adapters (outermost)
+    └── adapters/
+        ├── primary/  # Driving adapters (controllers, CLI)
+        └── secondary/# Driven adapters (DB, APIs)
+```
+
+## Layer Rules
+
+### Domain Layer
+- **NO external dependencies** (no frameworks, no libraries except language stdlib)
+- Contains pure business logic
+- Defines ports (interfaces) that the outside world must implement
+- Entities must have identity and lifecycle
+- Value Objects must be immutable
+
+### Application Layer
+- Orchestrates domain objects
+- Implements use cases
+- **Depends only on domain**
+- No direct infrastructure dependencies
+- Transaction boundaries defined here
+
+### Infrastructure Layer
+- Implements domain ports
+- Contains framework-specific code
+- Can depend on domain and application
+- Adapters translate between external world and domain
+
+## Dependency Rule
+
+```
+Infrastructure → Application → Domain
+     ↓               ↓           ↓
+  (outer)        (middle)    (inner)
+```
+
+**Dependencies always point inward.** Inner layers never know about outer layers.
+
+## Port Types
+
+### Input Ports (Driving)
+Interfaces that define what the application **offers**:
+```java
+public interface CreateOrderUseCase {
+    OrderId execute(CreateOrderCommand command);
+}
+```
+
+### Output Ports (Driven)
+Interfaces that define what the application **needs**:
+```java
+public interface OrderRepository {
+    Order findById(OrderId id);
+    void save(Order order);
+}
+```
+
+## Adapter Types
+
+### Primary Adapters (Driving)
+Drive the application:
+- REST Controllers
+- GraphQL Resolvers
+- CLI Commands
+- Message Consumers
+
+### Secondary Adapters (Driven)
+Driven by the application:
+- Database Repositories
+- External API Clients
+- Message Publishers
+- File System Access
+
+## Benefits
+
+1. **Testability**: Domain can be tested without infrastructure
+2. **Flexibility**: Easy to swap adapters (change DB, API, etc.)
+3. **Focus**: Business logic is isolated and clear
+4. **Independence**: Framework changes don't affect domain