Trade-offs in System Design

// Consistency spectrum from strongest to weakest

enum ConsistencyLevel {
  // Linearizability: reads always see the most recent write
  // Slowest, requires consensus (Raft/Paxos)
  LINEARIZABLE = "LINEARIZABLE",

  // Sequential consistency: operations appear in some total order
  // consistent with each client's program order
  SEQUENTIAL = "SEQUENTIAL",

  // Causal consistency: causally related operations are seen in order
  // Concurrent operations may be seen in any order
  CAUSAL = "CAUSAL",

  // Read-your-writes: a client always sees its own writes
  // Other clients may see stale data
  READ_YOUR_WRITES = "READ_YOUR_WRITES",

  // Eventual consistency: all replicas converge eventually
  // No ordering guarantees in the meantime
  EVENTUAL = "EVENTUAL",
}

// Practical example: user profile update
interface UserProfileService {
  // Strong consistency: user always sees their own updates immediately
  // Implementation: read from primary database
  updateProfile(userId: string, data: ProfileData): Promise<void>;
  getOwnProfile(userId: string): Promise<ProfileData>; // Read from primary

  // Eventual consistency: other users may see stale profile
  // Implementation: read from nearest replica
  getPublicProfile(userId: string): Promise<ProfileData>; // Read from replica
}

// Example: Database write strategies

// Optimize for latency: write-through
async function writeThrough(key: string, value: string): Promise<void> {
  // Write to DB synchronously, return when confirmed
  await database.write(key, value);  // 5ms
  await cache.set(key, value);       // 1ms
  // Total: ~6ms per write, but only handles ~160 writes/sec per connection
}

// Optimize for throughput: write-behind (buffering)
class WriteBuffer {
  private buffer: Map<string, string> = new Map();
  private flushInterval = 100; // ms

  async write(key: string, value: string): Promise<void> {
    this.buffer.set(key, value);
    await cache.set(key, value); // Immediate cache update
    // Return immediately - data will be flushed to DB asynchronously
    // Total: ~1ms per write, can handle thousands of writes/sec
    // Trade-off: data loss risk if process crashes before flush
  }

  private async flush(): Promise<void> {
    const batch = Array.from(this.buffer.entries());
    this.buffer.clear();
    await database.batchWrite(batch); // One DB call for many writes
  }
}

// Decision guide
function chooseDatabaseType(requirements: {
  needsJoins: boolean;
  needsACID: boolean;
  schemaIsStable: boolean;
  writeVolume: "low" | "medium" | "high" | "extreme";
  queryPatterns: "varied" | "known";
  dataRelationships: "simple" | "complex";
}): string {
  // Strong signals for SQL
  if (requirements.needsACID && requirements.needsJoins) {
    return "SQL (PostgreSQL recommended)";
  }

  // Strong signals for NoSQL
  if (requirements.writeVolume === "extreme" &&
      requirements.queryPatterns === "known" &&
      !requirements.needsJoins) {
    return "NoSQL (Cassandra for wide-column, DynamoDB for key-value)";
  }

  // Default recommendation
  if (requirements.dataRelationships === "complex") {
    return "SQL - complex relationships are hard to model in NoSQL";
  }

  return "Either works - choose based on team experience";
}

interface ArchitecturalDecision {
  title: string;
  context: string;          // What is the situation?
  options: Option[];
  decision: string;         // What did we choose?
  rationale: string;        // Why?
  consequences: string[];   // What are the implications?
}

interface Option {
  name: string;
  pros: string[];
  cons: string[];
  score: {
    complexity: number;     // 1 (simple) to 5 (complex)
    scalability: number;    // 1 (poor) to 5 (excellent)
    reliability: number;    // 1 (poor) to 5 (excellent)
    cost: number;           // 1 (cheap) to 5 (expensive)
    teamExperience: number; // 1 (none) to 5 (expert)
  };
}

// Example ADR (Architecture Decision Record)
const example: ArchitecturalDecision = {
  title: "Database for user sessions",
  context: "We need to store user sessions with ~1M concurrent users, " +
           "sub-10ms read latency, and automatic expiration.",
  options: [
    {
      name: "Redis",
      pros: [
        "Sub-millisecond reads",
        "Built-in TTL for expiration",
        "Team has experience",
      ],
      cons: [
        "Data loss on restart (unless persistence enabled)",
        "Memory cost for 1M sessions",
      ],
      score: { complexity: 1, scalability: 4, reliability: 3, cost: 3, teamExperience: 5 },
    },
    {
      name: "PostgreSQL",
      pros: [
        "Durable storage",
        "Rich querying for analytics",
        "Already in our stack",
      ],
      cons: [
        "Higher latency (~5ms)",
        "Need to implement expiration (cron job or pg_cron)",
      ],
      score: { complexity: 2, scalability: 3, reliability: 5, cost: 2, teamExperience: 5 },
    },
  ],
  decision: "Redis",
  rationale: "Session data is ephemeral - durability is not required. " +
             "The sub-ms latency is critical for user experience. " +
             "Memory cost for 1M sessions (~500MB) is acceptable.",
  consequences: [
    "Must handle Redis failover (use Redis Sentinel or Cluster)",
    "Cannot perform complex queries on session data",
    "Need monitoring for memory usage",
  ],
};