Software Architecture & System Design

bounded_contexts:
  user_management:
    entities:
      - User
      - Profile
      - Preferences
    aggregates:
      - UserAccount
    domain_events:
      - UserRegistered
      - ProfileUpdated
  
  order_management:
    entities:
      - Order
      - OrderItem
      - Payment
    aggregates:
      - OrderAggregate
    domain_events:
      - OrderPlaced
      - OrderShipped
      - PaymentProcessed

# Example: Service mesh configuration with Istio
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: user-service
spec:
  http:
  - match:
    - headers:
        user-type:
          exact: premium
    route:
    - destination:
        host: user-service
        subset: v2
  - route:
    - destination:
        host: user-service
        subset: v1
---
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: user-service
spec:
  host: user-service
  trafficPolicy:
    circuitBreaker:
      consecutiveErrors: 3
      interval: 30s
      baseEjectionTime: 30s
  subsets:
  - name: v1
    labels:
      version: v1
  - name: v2
    labels:
      version: v2

interface Event {
  id: string;
  aggregateId: string;
  eventType: string;
  eventData: any;
  timestamp: Date;
  version: number;
}

class EventStore {
  async saveEvents(aggregateId: string, events: Event[], expectedVersion: number): Promise<void> {
    // Optimistic concurrency control
    const currentVersion = await this.getLastVersion(aggregateId);
    if (currentVersion !== expectedVersion) {
      throw new ConcurrencyError('Version mismatch');
    }
    
    // Save events atomically
    await this.persistEvents(events);
    
    // Publish events to message bus
    await this.publishEvents(events);
  }
  
  async getEvents(aggregateId: string, fromVersion: number = 0): Promise<Event[]> {
    return await this.loadEvents(aggregateId, fromVersion);
  }
}

class Aggregate {
  private uncommittedEvents: Event[] = [];
  
  protected addEvent(event: Event): void {
    this.applyEvent(event);
    this.uncommittedEvents.push(event);
  }
  
  getUncommittedEvents(): Event[] {
    return this.uncommittedEvents;
  }
  
  markEventsAsCommitted(): void {
    this.uncommittedEvents = [];
  }
}

# Command side - Write operations
class CreateUserCommand:
    def __init__(self, user_id: str, email: str, name: str):
        self.user_id = user_id
        self.email = email
        self.name = name

class CreateUserCommandHandler:
    def __init__(self, user_repository: UserRepository):
        self.user_repository = user_repository
    
    def handle(self, command: CreateUserCommand):
        user = User.create(command.user_id, command.email, command.name)
        self.user_repository.save(user)
        
        # Publish domain events
        events = user.get_uncommitted_events()
        for event in events:
            self.event_bus.publish(event)

# Query side - Read operations
class UserQuery:
    def __init__(self, read_database):
        self.db = read_database
    
    def get_user_profile(self, user_id: str):
        return self.db.query(
            "SELECT * FROM user_profiles WHERE user_id = %s", 
            (user_id,)
        )
    
    def get_users_by_criteria(self, criteria: dict):
        # Optimized read queries with denormalized data
        pass

kafka_topics:
  user_events:
    partitions: 12
    replication_factor: 3
    configs:
      retention.ms: 604800000  # 7 days
      compression.type: lz4
  
  order_events:
    partitions: 24
    replication_factor: 3
    configs:
      retention.ms: 2592000000  # 30 days
      cleanup.policy: compact

consumer_groups:
  user_profile_updater:
    topics: [user_events]
    processing_guarantee: exactly_once
  
  order_analytics:
    topics: [order_events]
    processing_guarantee: at_least_once

api_design:
  resources:
    users:
      endpoints:
        - GET /api/v1/users
        - GET /api/v1/users/{id}
        - POST /api/v1/users
        - PUT /api/v1/users/{id}
        - DELETE /api/v1/users/{id}
      
      relationships:
        - GET /api/v1/users/{id}/orders
        - GET /api/v1/users/{id}/profile
  
  hypermedia_controls:
    - self_links
    - related_resources
    - available_actions
  
  versioning_strategy:
    - header_based: "Accept: application/vnd.api.v1+json"
    - url_based: "/api/v1/"
    - parameter_based: "?version=1"

// Example: API Gateway with rate limiting and authentication
const express = require('express');
const httpProxy = require('http-proxy-middleware');
const rateLimit = require('express-rate-limit');
const jwt = require('jsonwebtoken');

const app = express();

// Rate limiting middleware
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
});

// Authentication middleware
const authenticate = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }
  
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid token' });
  }
};

// Service routing
app.use('/api/users', limiter, authenticate, httpProxy({
  target: 'http://user-service:3001',
  changeOrigin: true,
  pathRewrite: {
    '^/api/users': '/users'
  }
}));

app.use('/api/orders', limiter, authenticate, httpProxy({
  target: 'http://order-service:3002',
  changeOrigin: true,
  pathRewrite: {
    '^/api/orders': '/orders'
  }
}));

type User {
  id: ID!
  email: String!
  name: String!
  profile: UserProfile
  orders: [Order!]!
}

type UserProfile {
  id: ID!
  avatar: String
  bio: String
  preferences: UserPreferences
}

type Order {
  id: ID!
  userId: ID!
  items: [OrderItem!]!
  total: Float!
  status: OrderStatus!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection
  order(id: ID!): Order
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUserProfile(userId: ID!, input: UpdateProfileInput!): UserProfile!
  createOrder(input: CreateOrderInput!): Order!
}

type Subscription {
  orderStatusChanged(userId: ID!): Order!
  userNotifications(userId: ID!): Notification!
}

class CachingService:
    def __init__(self):
        self.l1_cache = {}  # In-memory cache
        self.l2_cache = RedisClient()  # Distributed cache
        self.database = DatabaseClient()
    
    async def get_user(self, user_id: str):
        # L1 Cache check
        if user_id in self.l1_cache:
            return self.l1_cache[user_id]
        
        # L2 Cache check
        cached_user = await self.l2_cache.get(f"user:{user_id}")
        if cached_user:
            self.l1_cache[user_id] = cached_user
            return cached_user
        
        # Database query
        user = await self.database.get_user(user_id)
        if user:
            # Cache in both levels
            self.l1_cache[user_id] = user
            await self.l2_cache.set(f"user:{user_id}", user, ttl=3600)
        
        return user

# Cache invalidation strategy
class CacheInvalidation:
    def __init__(self, cache_service, event_bus):
        self.cache = cache_service
        self.event_bus = event_bus
        self.setup_event_handlers()
    
    def setup_event_handlers(self):
        self.event_bus.subscribe('UserUpdated', self.invalidate_user_cache)
        self.event_bus.subscribe('OrderPlaced', self.invalidate_user_orders_cache)
    
    async def invalidate_user_cache(self, event):
        await self.cache.delete(f"user:{event.user_id}")
        await self.cache.delete(f"user_orders:{event.user_id}")

-- Horizontal partitioning example
CREATE TABLE orders_2024_q1 PARTITION OF orders
FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');

CREATE TABLE orders_2024_q2 PARTITION OF orders
FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');

-- Vertical partitioning for hot/cold data
CREATE TABLE user_profiles_hot (
    user_id UUID PRIMARY KEY,
    email VARCHAR(255),
    last_login TIMESTAMP
);

CREATE TABLE user_profiles_cold (
    user_id UUID PRIMARY KEY,
    bio TEXT,
    preferences JSONB,
    created_at TIMESTAMP
);

monitoring_stack:
  metrics:
    - prometheus
    - grafana
    - alertmanager
  
  tracing:
    - jaeger
    - zipkin
    - opentelemetry
  
  logging:
    - elasticsearch
    - logstash
    - kibana
  
  application_metrics:
    - response_time
    - throughput
    - error_rate
    - cpu_usage
    - memory_usage
    - database_connections

class CircuitBreaker {
  private failureCount = 0;
  private lastFailureTime: number | null = null;
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
  
  constructor(
    private failureThreshold: number = 5,
    private recoveryTimeout: number = 60000,
    private monitoringPeriod: number = 10000
  ) {}
  
  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      if (this.shouldAttemptReset()) {
        this.state = 'HALF_OPEN';
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }
    
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
  
  private shouldAttemptReset(): boolean {
    return this.lastFailureTime !== null &&
           Date.now() - this.lastFailureTime >= this.recoveryTimeout;
  }
  
  private onSuccess(): void {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }
  
  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
    }
  }
}