Architecture Patterns

┌─────────────────────────────────────────────────┐
│                  Monolith                       │
│  ┌──────────┬──────────┬──────────┬──────────┐  │
│  │   UI     │  Users   │  Orders  │ Payments │  │
│  └──────────┴──────────┴──────────┴──────────┘  │
│  ┌─────────────────────────────────────────────┐│
│  │            Shared Database                  ││
│  └─────────────────────────────────────────────┘│
└─────────────────────────────────────────────────┘

┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│  User   │  │  Order  │  │ Payment │  │  Notif  │
│ Service │  │ Service │  │ Service │  │ Service │
└────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘
     │            │            │            │
     └────────────┴─────┬──────┴────────────┘
                        │
              ┌─────────┴─────────┐
              │    API Gateway    │
              └───────────────────┘
                        │
              ┌─────────┴─────────┐
              │      Clients      │
              └───────────────────┘

# Synchronous (HTTP/REST) -- Simple but creates tight coupling.
# If order-service is down, this entire call fails. Use when you
# need an immediate response (e.g., checkout flow showing order total).
import requests

def get_user_orders(user_id):
    user = requests.get(f"http://user-service/users/{user_id}").json()
    orders = requests.get(f"http://order-service/orders?user={user_id}").json()
    return {"user": user, "orders": orders}

# Asynchronous (Message Queue) -- Decoupled and resilient.
# The publisher does not care if consumers are slow or temporarily down.
# Use for tasks that do not need an immediate response (e.g., sending
# confirmation emails, updating analytics, syncing inventory).
import pika

def publish_order_created(order):
    channel.basic_publish(
        exchange='orders',
        routing_key='order.created',
        body=json.dumps(order)
    )

┌──────────────────────────────────────────────────────┐
│                    Event Bus                         │
└────┬─────────┬─────────┬─────────┬─────────┬────────┘
     │         │         │         │         │
     ▼         ▼         ▼         ▼         ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Order  │ │Inventory│ │ Payment│ │ Email  │ │Analytics│
│ Service│ │ Service │ │ Service│ │ Service│ │ Service│
└────────┘ └─────────┘ └────────┘ └────────┘ └─────────┘

# Store events, not state -- every change is an immutable fact that happened.
# This is how bank ledgers, Git version control, and event-sourced systems work.
class OrderEventStore:
    def append(self, event):
        # Events are immutable facts -- never update or delete them.
        self.events.append({
            "type": event.type,
            "data": event.data,
            "timestamp": datetime.now()
        })
    
    def get_order_state(self, order_id):
        # Replay all events to reconstruct current state.
        # For production systems, use snapshots to avoid replaying
        # thousands of events on every read (snapshot every N events).
        order = Order()
        for event in self.events:
            if event["data"]["order_id"] == order_id:
                order.apply(event)
        return order

# Event types -- each represents something that already happened (past tense)
OrderCreated(order_id="123", items=[...])
PaymentReceived(order_id="123", amount=100)
OrderShipped(order_id="123", tracking="XYZ")

Commands (Write)              Queries (Read)
     │                              │
     ▼                              ▼
┌─────────┐                  ┌─────────────┐
│ Command │                  │    Query    │
│ Handler │                  │   Handler   │
└────┬────┘                  └──────┬──────┘
     │                              │
     ▼                              ▼
┌─────────┐    Sync/         ┌───────────┐
│  Write  │ ─────────────►   │   Read    │
│   DB    │   Events         │   DB      │
└─────────┘                  └───────────┘

┌─────────────────────────────────────┐
│        Presentation Layer           │  ◄─── UI, Controllers, API endpoints
├─────────────────────────────────────┤
│         Application Layer           │  ◄─── Use Cases, Services, orchestration
├─────────────────────────────────────┤
│          Domain Layer               │  ◄─── Business Logic, Entities, rules
├─────────────────────────────────────┤
│        Infrastructure Layer         │  ◄─── DB, External APIs, messaging
└─────────────────────────────────────┘

# Clean Architecture Example
# The key rule: dependencies always point inward. The domain layer
# knows nothing about databases, HTTP, or frameworks. This makes
# your business logic testable without spinning up infrastructure.

# Domain Layer (innermost - ZERO external dependencies)
# This code should work identically whether your app uses
# PostgreSQL, MongoDB, or stores data in a spreadsheet.
class Order:
    def __init__(self, id, items):
        self.id = id
        self.items = items
        self.status = "pending"
    
    def calculate_total(self):
        return sum(item.price for item in self.items)

# Application Layer (use cases -- orchestrates domain objects)
# Contains application-specific business rules but stays ignorant
# of how data is persisted or how payments are actually processed.
class CreateOrderUseCase:
    def __init__(self, order_repo, payment_service):
        self.order_repo = order_repo          # Interface, not concrete class
        self.payment_service = payment_service  # Interface, not concrete class
    
    def execute(self, order_data):
        order = Order(**order_data)
        self.payment_service.process(order.calculate_total())
        self.order_repo.save(order)
        return order

# Infrastructure Layer (outermost -- the "dirty" details)
# Swap PostgresOrderRepository for MongoOrderRepository and
# the domain and application layers do not change at all.
class PostgresOrderRepository:
    def save(self, order):
        # SQL implementation details live here, nowhere else
        pass

class StripePaymentService:
    def process(self, amount):
        # Stripe API call -- if you switch to Braintree, only this file changes
        pass

                    ┌─────────────────────────────────────┐
                    │                                     │
    ┌───────────┐   │   ┌─────────────────────────────┐   │   ┌───────────┐
    │  REST API │───┼──►│          PORT               │   │   │  Database │
    │  Adapter  │   │   │    (Input Interface)        │   │   │  Adapter  │
    └───────────┘   │   └───────────┬─────────────────┘   │   └───────────┘
                    │               │                     │         ▲
    ┌───────────┐   │               ▼                     │         │
    │   CLI     │───┼──►┌─────────────────────────────┐   │   ┌─────┴─────┐
    │  Adapter  │   │   │                             │   │   │   PORT    │
    └───────────┘   │   │      DOMAIN / CORE          │◄──┼───│  (Output) │
                    │   │    (Business Logic)         │   │   └───────────┘
    ┌───────────┐   │   │                             │   │         │
    │   gRPC    │───┼──►└─────────────────────────────┘   │         ▼
    │  Adapter  │   │               │                     │   ┌───────────┐
    └───────────┘   │               ▼                     │   │   Email   │
                    │   ┌─────────────────────────────┐   │   │  Adapter  │
                    │   │          PORT               │───┼──►└───────────┘
                    │   │    (Output Interface)       │   │
                    │   └─────────────────────────────┘   │
                    │                                     │
                    └─────────────────────────────────────┘

# Port (Interface) -- defines WHAT the domain needs, not HOW it's done.
# This is the "socket shape" that adapters must match.
from abc import ABC, abstractmethod

class UserRepository(ABC):
    @abstractmethod
    def save(self, user: User) -> None: pass
    
    @abstractmethod
    def find_by_id(self, user_id: str) -> User: pass

# Adapter (Implementation) -- the concrete plug that fits the socket.
# You can swap PostgresUserRepository for InMemoryUserRepository in
# tests without touching any business logic.
class PostgresUserRepository(UserRepository):
    def __init__(self, connection):
        self.connection = connection
    
    def save(self, user: User) -> None:
        self.connection.execute(
            "INSERT INTO users ...", user.to_dict()
        )
    
    def find_by_id(self, user_id: str) -> User:
        row = self.connection.query("SELECT * FROM users WHERE id = ?", user_id)
        return User.from_dict(row)

# Domain service (core business logic, no external dependencies).
# Notice: UserService depends on the abstract UserRepository port,
# never on PostgresUserRepository directly. This is the power of
# hexagonal architecture -- your domain is framework-agnostic.
class UserService:
    def __init__(self, user_repo: UserRepository):  # Inject port, not adapter
        self.user_repo = user_repo
    
    def register_user(self, name: str, email: str) -> User:
        user = User(name=name, email=email)
        user.validate()  # Business rule enforcement stays in the domain
        self.user_repo.save(user)
        return user

┌─────────────────────────────────────────────────────────────────┐
│                        E-Commerce System                        │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   Order Context │  Catalog Context│     Shipping Context        │
│                 │                 │                             │
│  - Order        │  - Product      │  - Shipment                 │
│  - OrderItem    │  - Category     │  - Carrier                  │
│  - Customer*    │  - Inventory    │  - TrackingInfo             │
│                 │                 │  - Customer*                │
│                 │                 │                             │
│  * Different    │                 │  * Different view of        │
│    view of      │                 │    Customer than in         │
│    Customer     │                 │    Order Context            │
└─────────────────┴─────────────────┴─────────────────────────────┘
        │                   │                      │
        └───────────────────┼──────────────────────┘
                            │
                   Anti-Corruption Layer
                   (Context Mapping)

# Entity (has identity)
class Order:
    def __init__(self, order_id: str):
        self.id = order_id  # Identity
        self.items = []
        self.status = "pending"
    
    def add_item(self, product_id: str, quantity: int, price: Decimal):
        self.items.append(OrderItem(product_id, quantity, price))
    
    def calculate_total(self) -> Decimal:
        return sum(item.subtotal for item in self.items)

# Value Object (no identity, immutable)
@dataclass(frozen=True)
class Money:
    amount: Decimal
    currency: str
    
    def add(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("Currency mismatch")
        return Money(self.amount + other.amount, self.currency)

# Aggregate (cluster of entities with a root)
class Order:  # Aggregate Root
    def __init__(self, order_id: str, customer_id: str):
        self.id = order_id
        self.customer_id = customer_id
        self._items: List[OrderItem] = []  # Part of aggregate
    
    def add_item(self, product: Product, quantity: int):
        # Business rule: max 10 items per order
        if len(self._items) >= 10:
            raise DomainError("Order cannot have more than 10 items")
        self._items.append(OrderItem(product.id, quantity, product.price))

# Domain Event
@dataclass
class OrderPlaced:
    order_id: str
    customer_id: str
    total: Decimal
    timestamp: datetime

# Repository (persistence abstraction)
class OrderRepository(ABC):
    @abstractmethod
    def save(self, order: Order) -> None: pass
    
    @abstractmethod
    def find_by_id(self, order_id: str) -> Optional[Order]: pass

Order Service         Payment Service       Inventory Service
     │                      │                      │
     │   OrderCreated       │                      │
     ├─────────────────────►│                      │
     │                      │   PaymentProcessed   │
     │                      ├─────────────────────►│
     │                      │                      │
     │                      │   InventoryReserved  │
     │◄─────────────────────┼──────────────────────┤
     │                      │                      │
     │  OrderConfirmed      │                      │
     │                      │                      │

Compensation (if Inventory fails):
     │                      │   InventoryFailed    │
     │◄─────────────────────┼──────────────────────┤
     │   RefundPayment      │                      │
     ├─────────────────────►│                      │
     │   OrderCancelled     │                      │

class OrderSagaOrchestrator:
    """Central coordinator that manages the distributed transaction.
    Each step has a compensating action -- if step N fails,
    we undo steps N-1, N-2, ... in reverse order."""
    
    def __init__(self, payment_service, inventory_service, notification_service):
        self.payment = payment_service
        self.inventory = inventory_service
        self.notification = notification_service
    
    def execute(self, order: Order):
        try:
            # Step 1: Process payment (can fail if card declined)
            payment_id = self.payment.process(order.total)
            
            # Step 2: Reserve inventory (can fail if out of stock)
            try:
                self.inventory.reserve(order.items)
            except InventoryError:
                # Compensate step 1: refund the payment we already took
                self.payment.refund(payment_id)
                raise
            
            # Step 3: Send confirmation (best-effort, retry on failure)
            self.notification.send_confirmation(order)
            
            return SagaResult.success(order.id)
            
        except Exception as e:
            return SagaResult.failure(str(e))

                                    ┌─────────────────┐
                                    │  User Service   │
                                    └────────▲────────┘
                                             │
┌──────────┐      ┌─────────────────┐       │       ┌─────────────────┐
│  Mobile  │─────►│                 │───────┼──────►│  Order Service  │
│   App    │      │   API Gateway   │       │       └─────────────────┘
└──────────┘      │                 │       │
                  │  • Auth         │       │       ┌─────────────────┐
┌──────────┐      │  • Rate Limit   │───────┼──────►│ Payment Service │
│   Web    │─────►│  • Routing      │       │       └─────────────────┘
│   App    │      │  • Aggregation  │       │
└──────────┘      │  • Caching      │       │       ┌─────────────────┐
                  │  • SSL Term     │───────┴──────►│  Catalog Service│
┌──────────┐      │  • Logging      │               └─────────────────┘
│  Partner │─────►│                 │
│   API    │      └─────────────────┘
└──────────┘

┌──────────┐      ┌─────────────────┐
│  Mobile  │─────►│   Mobile BFF    │────┐
│   App    │      └─────────────────┘    │
└──────────┘                             │    ┌─────────────────┐
                                         ├───►│    Services     │
┌──────────┐      ┌─────────────────┐    │    └─────────────────┘
│   Web    │─────►│    Web BFF      │────┤
│   App    │      └─────────────────┘    │
└──────────┘                             │
                                         │
┌──────────┐      ┌─────────────────┐    │
│  Admin   │─────►│   Admin BFF     │────┘
│  Panel   │      └─────────────────┘
└──────────┘

import time
from enum import Enum

class CircuitState(Enum):
    CLOSED = "closed"        # Normal operation -- requests flow through
    OPEN = "open"            # Failing -- reject requests immediately (fail fast)
    HALF_OPEN = "half_open"  # Recovery test -- allow one request to probe health

class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=30):
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.failure_count = 0
        self.last_failure_time = None
        self.state = CircuitState.CLOSED
    
    def call(self, func, *args, **kwargs):
        if self.state == CircuitState.OPEN:
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = CircuitState.HALF_OPEN
            else:
                raise CircuitOpenError("Circuit is open")
        
        try:
            result = func(*args, **kwargs)
            self._on_success()
            return result
        except Exception as e:
            self._on_failure()
            raise
    
    def _on_success(self):
        self.failure_count = 0
        self.state = CircuitState.CLOSED
    
    def _on_failure(self):
        self.failure_count += 1
        self.last_failure_time = time.time()
        if self.failure_count >= self.failure_threshold:
            self.state = CircuitState.OPEN

# Usage -- wrap any unreliable external call with a circuit breaker.
# In production, use battle-tested libraries like resilience4j (Java),
# Polly (.NET), or pybreaker (Python) instead of rolling your own.
circuit = CircuitBreaker(failure_threshold=3, recovery_timeout=60)

try:
    result = circuit.call(external_service.fetch_data)
except CircuitOpenError:
    # Graceful degradation: serve stale cached data rather than
    # showing an error page. Users get slightly outdated data,
    # which is almost always better than no data at all.
    result = cached_data  # Fallback

┌─────────────────────────────────────────────────────────────────┐
│                         Service Mesh                            │
│                                                                 │
│  ┌─────────────────────┐      ┌─────────────────────┐          │
│  │    Service A        │      │    Service B        │          │
│  │  ┌─────────────┐    │      │  ┌─────────────┐    │          │
│  │  │   App Code  │    │      │  │   App Code  │    │          │
│  │  └──────┬──────┘    │      │  └──────┬──────┘    │          │
│  │         │           │      │         │           │          │
│  │  ┌──────┴──────┐    │      │  ┌──────┴──────┐    │          │
│  │  │   Sidecar   │◄───┼──────┼─►│   Sidecar   │    │          │
│  │  │   Proxy     │    │      │  │   Proxy     │    │          │
│  │  │ (Envoy)     │    │      │  │ (Envoy)     │    │          │
│  │  └─────────────┘    │      │  └─────────────┘    │          │
│  └─────────────────────┘      └─────────────────────┘          │
│              │                          │                       │
│              └──────────┬───────────────┘                       │
│                         │                                       │
│              ┌──────────┴──────────┐                           │
│              │    Control Plane    │                           │
│              │  (Istio, Linkerd)   │                           │
│              └─────────────────────┘                           │
│                                                                 │
│  Features: mTLS, Load Balancing, Circuit Breaking,             │
│           Observability, Traffic Management                     │
└─────────────────────────────────────────────────────────────────┘

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
We need a database for our e-commerce platform that handles:
- Complex queries with JOINs
- ACID transactions for orders
- ~1M daily transactions

## Decision
Use PostgreSQL as our primary database.

## Consequences
### Positive
- Strong ACID compliance
- Rich query capabilities
- Mature ecosystem

### Negative
- Horizontal scaling is complex
- May need read replicas for scale

### Neutral
- Team has moderate PostgreSQL experience