The Software Engineer Roadmap in the AI Age: What Claude Can't Code for You

# The AI-Augmented Engineering Workflow

# YOU define:       "We need a payment service that handles
#                    webhooks from Stripe, updates user balances atomically,
#                    retries failed events up to 3 times, and emits an event
#                    to our notification bus. Use PostgreSQL with row-level locking."

# AI executes:       [Full implementation code generated]

# YOU validate:      Review for race conditions, missing error handling,
#                    security gaps, and schema decisions

# YOU integrate:     Decide how this service talks to billing, inventory, analytics

# AI helps again:    Write the tests, generate the OpenAPI spec, write the docs

# YOU ship:          With confidence in the system design decision

# Architectural Patterns Overview

┌─────────────────────────────────────────────────────────────┐
│                  ARCHITECTURAL PATTERNS MAP                  │
├─────────────────┬───────────────────┬───────────────────────┤
│   PATTERN       │   BEST FOR        │   AVOID WHEN          │
├─────────────────┼───────────────────┼───────────────────────┤
│ Monolith        │ Early startups    │ Team > 10 engineers   │
│                 │ Simple domains    │ Need independent scale│
├─────────────────┼───────────────────┼───────────────────────┤
│ Modular Mono    │ Medium teams      │ Services need diff     │
│                 │ Single deploy     │ tech stacks           │
├─────────────────┼───────────────────┼───────────────────────┤
│ Microservices   │ Large teams       │ Small teams < 5       │
│                 │ Independent scale │ Low traffic products  │
├─────────────────┼───────────────────┼───────────────────────┤
│ Event-Driven    │ High decoupling   │ Need strong           │
│                 │ Async workflows   │ consistency           │
├─────────────────┼───────────────────┼───────────────────────┤
│ Serverless      │ Variable load     │ Long-running tasks    │
│                 │ Low ops overhead  │ Cold start sensitive  │
├─────────────────┼───────────────────┼───────────────────────┤
│ CQRS + ES       │ Audit-heavy apps  │ Simple CRUD apps      │
│                 │ Complex domains   │ Small teams           │
└─────────────────┴───────────────────┴───────────────────────┘

// SOLID Applied — Real-World Example

// ❌ BAD: God class that violates Single Responsibility
class UserService {
  createUser() { /* user creation */ }
  sendWelcomeEmail() { /* email sending */ }
  generateReport() { /* reporting */ }
  processPayment() { /* payment */ }
}

// ✅ GOOD: Each class has one reason to change
class UserRepository {
  async create(dto: CreateUserDto): Promise<User> { /* persistence only */ }
}

class EmailService {
  async sendWelcome(user: User): Promise<void> { /* email only */ }
}

class UserOnboardingService {
  constructor(
    private readonly users: UserRepository,
    private readonly email: EmailService
  ) {}

  async onboard(dto: CreateUserDto): Promise<User> {
    const user = await this.users.create(dto);
    await this.email.sendWelcome(user);
    return user;
  }
}

// This separation lets AI generate each class independently
// and lets YOU orchestrate them correctly

# CAP Theorem Decision Framework

┌──────────────────────────────────────────────────────────────┐
│                    CAP THEOREM MATRIX                        │
├──────────────────┬──────────────────┬────────────────────────┤
│  CP (Consistent  │  AP (Available + │  Decision Factors      │
│  + Partition)    │  Partition)      │                        │
├──────────────────┼──────────────────┼────────────────────────┤
│  MongoDB*        │  CouchDB         │  Use CP when:          │
│  HBase           │  DynamoDB        │  • Financial data      │
│  Zookeeper       │  Cassandra       │  • Inventory counts    │
│  etcd            │  Riak            │  • User auth tokens    │
├──────────────────┼──────────────────┼────────────────────────┤
│                  │                  │  Use AP when:          │
│                  │                  │  • Social feeds        │
│                  │                  │  • Shopping carts      │
│                  │                  │  • Metrics/analytics   │
└──────────────────┴──────────────────┴────────────────────────┘

*MongoDB default is CP but configurable

Key insight: "Eventual Consistency" = AP system.
             Data will be consistent — eventually.
             Your UI needs to account for this.

# API Design Decision Tree

Who is the consumer?
  │
  ├─ External (public API, third parties)
  │    └─ Use REST + OpenAPI spec
  │         • Widely understood
  │         • Easy to document
  │         • Language agnostic
  │
  ├─ Internal service-to-service (backend)
  │    ├─ Need performance + streaming → gRPC
  │    │   • Protobuf binary encoding (3-10x faster than JSON)
  │    │   • Bi-directional streaming
  │    │   • Strongly typed contracts
  │    │
  │    └─ Need flexibility → REST or GraphQL
  │
  └─ Frontend (web/mobile) with complex queries
       └─ Use GraphQL
            • Client defines its data needs
            • No over/under-fetching
            • Strong tooling (Apollo, urql)

# REST API Design Rules (Non-Negotiable)

✅ Use nouns, not verbs: /users, /orders — NOT /getUser, /createOrder
✅ Use HTTP methods semantically: GET (read), POST (create), PUT (full update),
   PATCH (partial update), DELETE (remove)
✅ Return consistent error shapes: { error: { code, message, details } }
✅ Version your API: /api/v1/users — never break existing consumers
✅ Use pagination: cursor-based > offset for large datasets
✅ Rate limit: protect your services from abuse

// Production-Grade REST API Response Structure
// This is the contract AI generates code around — YOU define it

interface ApiResponse<T> {
  data: T | null;
  error: ApiError | null;
  meta: {
    timestamp: string;
    requestId: string;
    version: string;
  };
  pagination?: {
    cursor: string | null;
    hasMore: boolean;
    total: number;
  };
}

interface ApiError {
  code: string;          // Machine-readable: 'USER_NOT_FOUND'
  message: string;       // Human-readable: 'The user was not found'
  details?: unknown;     // Validation errors, additional context
  stack?: string;        // Only in development
}

// Example: Payment Service endpoint definition
// YOU write this spec, AI writes the implementation

/**
 * POST /api/v1/payments
 * Creates a new payment transaction
 *
 * @security BearerAuth
 * @body CreatePaymentDto
 * @returns ApiResponse<Payment>
 * @throws 400 - Validation error
 * @throws 402 - Insufficient funds
 * @throws 409 - Duplicate transaction
 * @throws 503 - Payment processor unavailable
 */

# Scaling Layers — Apply in Order (Don't over-engineer early)

Layer 1: Application Optimization (free)
  ├─ Profile and eliminate N+1 queries
  ├─ Add database indexes on filtered columns
  ├─ Implement connection pooling (PgBouncer for PostgreSQL)
  └─ Async processing for non-critical paths

Layer 2: Caching (cheap, high ROI)
  ├─ In-memory cache (Redis) for hot data
  │   • Session storage
  │   • Rate limiting counters
  │   • Frequently accessed DB results
  ├─ HTTP caching headers (Cache-Control, ETag)
  └─ CDN for static assets and edge caching

Layer 3: Database Optimization
  ├─ Read replicas for read-heavy workloads
  ├─ Write replicas / primary-secondary setup
  ├─ Database sharding (horizontal partitioning)
  └─ CQRS — separate read and write models

Layer 4: Horizontal Scaling
  ├─ Stateless services + load balancer
  ├─ Kubernetes for container orchestration
  ├─ Auto-scaling policies based on CPU/memory/custom metrics
  └─ Multi-region deployment for global users

# Caching Strategy: The Cache-Aside Pattern
# This is what you design; AI generates the implementation

async getUser(userId: string) {
  // 1. Check cache first
  const cached = await redis.get(`user:${userId}`);
  if (cached) return JSON.parse(cached);

  // 2. Cache miss — fetch from database
  const user = await db.users.findById(userId);
  if (!user) throw new NotFoundError('USER_NOT_FOUND');

  // 3. Store in cache with TTL
  await redis.setex(`user:${userId}`, 3600, JSON.stringify(user));

  return user;
}

# Database Selection Framework

┌────────────────────────────────────────────────────────────────┐
│              DATABASE SELECTION DECISION TREE                  │
└────────────────────────────────────────────────────────────────┘

Do you need ACID transactions? (financial, inventory, auth)
  YES → Relational DB
        ├─ PostgreSQL  — Best default. JSONB, full-text search, extensions
        ├─ MySQL/MariaDB — High-read web workloads, simple transactions
        └─ SQLite — Edge/embedded, testing environments

Do you need massive write throughput? (IoT, events, logs)
  YES → Time-Series / Wide-column
        ├─ InfluxDB    — IoT, metrics, time-series data
        ├─ Cassandra   — Multi-region, high write throughput
        └─ ClickHouse  — Analytics, OLAP queries at massive scale

Do you need flexible schemas or document storage?
  YES → Document DB
        ├─ MongoDB     — Flexible docs, aggregation pipeline
        ├─ Firestore   — Real-time sync, mobile-first apps
        └─ DynamoDB    — Serverless, key-value, predictable latency

Do you need graph relationships? (social networks, fraud detection)
  YES → Graph DB
        ├─ Neo4j       — Most mature, Cypher query language
        └─ ArangoDB    — Multi-model (graph + document + key-value)

Do you need full-text search / relevance ranking?
  YES → Search Engine (alongside your primary DB)
        ├─ Elasticsearch / OpenSearch — Enterprise search, analytics
        └─ Algolia     — Managed, fast, developer-friendly

Do you need cache / ephemeral data?
  YES → In-memory Store
        ├─ Redis       — Sessions, queues, pub/sub, rate limiting
        └─ Memcached   — Simple key-value cache, high throughput

# Rule: Start with PostgreSQL. Add specialized stores when you hit real limits.

// Data Modeling Principles — Applied Example
// Designing a multi-tenant SaaS payment system

// ❌ NAIVE DESIGN — will cause problems at scale
CREATE TABLE payments (
  id UUID PRIMARY KEY,
  user_id UUID,           -- No foreign key constraint
  amount DECIMAL,         -- No precision specified
  status VARCHAR(20),     -- Magic strings, no enum
  data JSON,              -- Unbounded, hard to query
  created TIMESTAMP       -- No timezone handling
);

// ✅ PRODUCTION-READY DESIGN
CREATE TYPE payment_status AS ENUM (
  'pending', 'processing', 'completed', 'failed', 'refunded'
);

CREATE TABLE payments (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id       UUID NOT NULL REFERENCES tenants(id),  -- Multi-tenancy
  user_id         UUID NOT NULL REFERENCES users(id),
  amount          DECIMAL(19, 4) NOT NULL,               -- Currency precision
  currency        CHAR(3) NOT NULL DEFAULT 'USD',        -- ISO 4217
  status          payment_status NOT NULL DEFAULT 'pending',
  idempotency_key VARCHAR(255) UNIQUE NOT NULL,          -- Prevent duplicates
  processor_ref   VARCHAR(255),                          -- External reference
  metadata        JSONB,                                 -- Flexible extension
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),    -- Timezone-aware
  updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

  -- Composite index for the most common query patterns
  CONSTRAINT chk_amount_positive CHECK (amount > 0)
);

CREATE INDEX idx_payments_tenant_user ON payments(tenant_id, user_id);
CREATE INDEX idx_payments_status ON payments(status) WHERE status != 'completed';
CREATE INDEX idx_payments_created ON payments(created_at DESC);
CREATE INDEX idx_payments_idempotency ON payments(idempotency_key);

-- YOU design this schema, AI generates migrations and ORM models

# Modern Data Stack Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   DATA PIPELINE ARCHITECTURE                    │
└─────────────────────────────────────────────────────────────────┘

  [Sources]           [Ingestion]         [Storage]     [Analytics]

  PostgreSQL    ──►   Debezium CDC   ──►  Data          Apache
  MySQL         ──►   (Change Data        Warehouse ──►  Superset
  MongoDB       ──►    Capture)      ──►  (BigQuery,     Metabase
  Stripe API    ──►                  ──►   Snowflake,    Grafana
  Kafka Events  ──►   Apache Kafka        Redshift,      PowerBI
                ──►   or Flink       ──►   ClickHouse)

  [Transform layer: dbt (data build tool)]
  └─ SQL-based transformations
  └─ Versioned, testable data models
  └─ Lineage tracking

# Key Patterns

CDC (Change Data Capture): Capture every INSERT/UPDATE/DELETE
  └─ Tools: Debezium, AWS DMS, Fivetran

Event Streaming: Real-time pipeline
  └─ Tools: Apache Kafka, AWS Kinesis, Redpanda

Batch ETL: Scheduled full extracts
  └─ Tools: Apache Airflow, Prefect, dbt

Reverse ETL: Push analytics back to operational systems
  └─ Tools: Census, Hightouch

# Critical Decision: ELT vs ETL
# ETL: Transform before loading (on-premise, sensitive data)
# ELT: Load raw, then transform (modern cloud warehouses)
# Recommendation: Use ELT with dbt on BigQuery/Snowflake/ClickHouse

# Service Decomposition Using Domain-Driven Design

# E-Commerce Platform Example

┌─────────────────────────────────────────────────────────────────┐
│                    BOUNDED CONTEXT MAP                          │
└─────────────────────────────────────────────────────────────────┘

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Identity   │   │   Catalog    │   │   Inventory  │
│   Service    │   │   Service    │   │   Service    │
│              │   │              │   │              │
│ • Auth       │   │ • Products   │   │ • Stock      │
│ • Users      │   │ • Categories │   │ • Warehouses │
│ • Roles      │   │ • Search     │   │ • Reservations│
│ • Tenants    │   │ • Pricing    │   │              │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │ (Event Bus)
       ┌──────────────────┼──────────────────┐
       │                  │                  │
┌──────┴───────┐   ┌──────┴───────┐   ┌──────┴───────┐
│    Orders    │   │   Payments   │   │Notifications │
│   Service    │   │   Service    │   │   Service    │
│              │   │              │   │              │
│ • Cart       │   │ • Transactions│  │ • Email      │
│ • Orders     │   │ • Refunds    │   │ • SMS        │
│ • Fulfillment│   │ • Invoices   │   │ • Push       │
└──────────────┘   └──────────────┘   └──────────────┘

# Boundary Rules:
# 1. Services own their data — NO shared databases
# 2. Each service has a single team responsible
# 3. Communication is via events or APIs — never direct DB access
# 4. A service should be independently deployable
# 5. If you always deploy two services together, merge them

// Synchronous Communication — REST/gRPC
// Use when: you need an immediate response, strong consistency required

// Order Service calling Inventory Service
async reserveStock(orderId: string, items: OrderItem[]): Promise<Reservation> {
  const response = await inventoryClient.post('/reservations', {
    orderId,
    items,
    timeout: 5000,          // Fail fast — don't block forever
    retries: 3,             // Retry on transient failures
    circuitBreaker: true    // Open circuit after 5 consecutive failures
  });
  return response.data;
}

// Asynchronous Communication — Event-Driven (Kafka/RabbitMQ)
// Use when: high throughput, decoupling, eventual consistency acceptable

// Order Service emits event — doesn't care who handles it
async placeOrder(order: Order): Promise<void> {
  await this.orderRepository.save(order);

  // Emit event — Inventory, Notifications, Analytics all subscribe
  await this.eventBus.publish('order.placed', {
    orderId: order.id,
    customerId: order.customerId,
    items: order.items,
    totalAmount: order.totalAmount,
    timestamp: new Date().toISOString()
  });

  // Returns immediately — no waiting for downstream services
}

// Inventory Service handles the event independently
@EventHandler('order.placed')
async onOrderPlaced(event: OrderPlacedEvent): Promise<void> {
  await this.inventoryService.reserveStock(event.orderId, event.items);

  // If this fails, the message queue retries automatically
  // Idempotency key prevents double-processing
}

// Resilience Patterns — Critical for Production Systems

// 1. CIRCUIT BREAKER: Prevent cascade failures
// When downstream service is failing, stop calling it
const paymentCircuitBreaker = new CircuitBreaker(paymentClient.charge, {
  failureThreshold: 5,      // Open after 5 consecutive failures
  successThreshold: 2,      // Close after 2 consecutive successes
  timeout: 10000,           // Consider failure if no response in 10s
  resetTimeout: 30000,      // Try again after 30s
  fallback: async (error) => {
    // Queue the payment for later retry instead of failing user
    await this.paymentRetryQueue.add({ error });
    return { status: 'queued', message: 'Payment will be processed shortly' };
  }
});

// 2. RETRY WITH EXPONENTIAL BACKOFF: Handle transient failures
async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      if (!isTransientError(error)) throw error; // Don't retry 4xx errors

      const delay = Math.min(1000 * Math.pow(2, attempt), 30000); // Max 30s
      const jitter = Math.random() * 1000; // Prevent thundering herd
      await sleep(delay + jitter);
    }
  }
}

// 3. BULKHEAD: Isolate failures to prevent resource exhaustion
// Separate connection pools for critical vs non-critical operations
const criticalPool = new ConnectionPool({ max: 20 }); // Payment, Auth
const analyticsPool = new ConnectionPool({ max: 5 });  // Reports, Metrics

// 4. SAGA PATTERN: Distributed transactions without 2PC
// Each step has a compensating action that undoes it on failure
class OrderSaga {
  async execute(order: Order): Promise<void> {
    const steps = [
      { action: () => inventory.reserve(order), compensate: () => inventory.release(order) },
      { action: () => payment.charge(order),    compensate: () => payment.refund(order) },
      { action: () => shipping.schedule(order), compensate: () => shipping.cancel(order) },
    ];
    // Run steps sequentially, rollback on failure
  }
}

# Observability Stack — The Modern Standard

┌─────────────────────────────────────────────────────────────────┐
│                    OBSERVABILITY STACK                          │
└─────────────────────────────────────────────────────────────────┘

  LOGS (What happened?)
  ├─ Structured JSON logging (Winston, Pino, Serilog)
  ├─ Centralized: Elasticsearch + Kibana, or Loki + Grafana
  ├─ Include: requestId, userId, tenantId, service, severity
  └─ Correlation IDs across service boundaries

  METRICS (How is the system behaving?)
  ├─ Prometheus: time-series metrics collection
  ├─ Grafana: dashboards and alerting
  ├─ Key metrics: RED method
  │   ├─ Rate:    requests per second
  │   ├─ Errors:  error rate percentage
  │   └─ Duration: p50, p95, p99 response time
  └─ USE method for infrastructure:
      ├─ Utilization (CPU, Memory %)
      ├─ Saturation (queue depth, backlog)
      └─ Errors (disk errors, network drops)

  TRACES (Where did the time go?)
  ├─ OpenTelemetry: vendor-neutral instrumentation
  ├─ Jaeger or Zipkin: distributed trace visualization
  ├─ Show: exactly which service, query, or API call is slow
  └─ Critical for debugging multi-service request flows

# Golden Signal Alerting Rule:
# Alert on symptoms, not causes
# ✅ Alert: "Error rate > 1% for 5 minutes"
# ❌ Alert: "CPU > 80%" (might be fine)
# Alert ONLY on things that require human action

// Zero Trust Implementation Patterns

// 1. Never trust caller identity without verification
// Every service-to-service call must be authenticated

// ❌ Insecure: Trust the caller based on network location
async getUser(userId: string, callerService: string): Promise<User> {
  if (callerService === 'orders-service') { // Anyone can claim this!
    return db.users.findById(userId);
  }
  throw new UnauthorizedError();
}

// ✅ Secure: Verify JWT signed by your identity provider
async getUser(userId: string, token: string): Promise<User> {
  const claims = await jwtVerifier.verify(token, {
    issuer: 'https://auth.yourdomain.com',
    audience: 'user-service'
  });

  // Verify the caller has permission to read this specific user
  if (!claims.scopes.includes('users:read')) throw new ForbiddenError();
  if (claims.tenantId !== (await db.users.findById(userId)).tenantId) {
    throw new ForbiddenError(); // Can't read another tenant's users
  }

  return db.users.findById(userId);
}

// 2. Principle of Least Privilege — DB user permissions
-- Each service gets ONLY the permissions it needs
CREATE USER order_service_user WITH PASSWORD '...';
GRANT SELECT, INSERT, UPDATE ON orders TO order_service_user;
GRANT SELECT ON users TO order_service_user; -- Read-only on users
-- NO: Don't grant SUPERUSER or unrestricted access

// 3. Encrypt data at rest AND in transit
// Sensitive fields must be encrypted even in the database
const encryptedCard = await encryption.encrypt(cardNumber, {
  algorithm: 'AES-256-GCM',
  keyId: 'payment-key-v2',   // Key rotation support
  aad: userId                // Additional authenticated data
});

# Compliance Frameworks: What They Mean for Architecture

┌─────────────────────────────────────────────────────────────────┐
│                 COMPLIANCE IMPACT ON ARCHITECTURE               │
└─────────────────────────────────────────────────────────────────┘

GDPR (EU Data Protection)
  Architectural Impacts:
  ├─ Data residency: EU data must stay in EU regions
  ├─ Right to erasure: design deletion into your schema from day one
  │   └─ Use soft deletes + scheduled hard deletes
  │   └─ Anonymization pipelines for analytics
  ├─ Data minimization: only collect what you need
  ├─ Consent management: log when/what user consented to
  ├─ Data portability: export endpoint required (JSON/CSV)
  └─ Breach notification: incident response + audit logging

SOC 2 Type II (Trust Service Criteria)
  Architectural Impacts:
  ├─ Availability: SLA requirements, monitoring, runbooks
  ├─ Confidentiality: encryption, access controls, audit logs
  ├─ Security: vulnerability management, penetration testing
  ├─ Processing Integrity: data validation, error handling
  └─ Privacy: consent management, data retention policies

PCI DSS (Payment Card Industry)
  Architectural Impacts:
  ├─ Never store raw card numbers — use tokenization
  ├─ Separate card data environment (CDE) from rest of system
  ├─ Encryption in transit (TLS 1.2+) AND at rest
  ├─ Strict access logging for all card data access
  └─ Regular vulnerability scans and penetration testing

Key Rule: Compliance is a SYSTEM DESIGN CONSTRAINT.
          AI generates code. YOU ensure the code satisfies
          your regulatory requirements.

// OWASP Top 10 — What to audit in AI-generated code

// 1. INJECTION ATTACKS — Most common AI mistake
// ❌ AI might generate: (SQL injection vulnerability)
const query = `SELECT * FROM users WHERE email = '${email}'`; // Dangerous!

// ✅ Always use parameterized queries:
const user = await db.query('SELECT * FROM users WHERE email = $1', [email]);

// 2. BROKEN ACCESS CONTROL — AI forgets authorization checks
// ❌ AI might generate:
app.get('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id); // No auth check!
  res.json(user);
});

// ✅ Always verify: is the caller allowed to access THIS resource?
app.get('/api/users/:id', authenticate, async (req, res) => {
  if (req.user.id !== req.params.id && !req.user.roles.includes('admin')) {
    return res.status(403).json({ error: 'FORBIDDEN' });
  }
  const user = await db.users.findById(req.params.id);
  res.json(sanitize(user)); // Never return password_hash!
});

// 3. CRYPTOGRAPHIC FAILURES — AI uses deprecated algorithms
// ❌ Don't use MD5, SHA1, or unsalted hashes for passwords
const hash = crypto.createHash('md5').update(password).digest('hex'); // Broken!

// ✅ Use bcrypt, argon2, or scrypt for passwords
const hash = await argon2.hash(password, {
  type: argon2.argon2id,
  memoryCost: 65536,  // 64MB
  timeCost: 3,
  parallelism: 1
});

// 4. SECURITY MISCONFIGURATION — AI doesn't know your environment
// Always check: CORS settings, error messages, debug endpoints,
// default credentials, security headers

// ✅ Security headers (set at infrastructure or application level)
app.use(helmet()); // Sets X-Frame-Options, CSP, HSTS, etc.

# Context Engineering: The ARCH Framework for AI Prompting

A — Architecture Context
   Tell AI about your system architecture before asking for code
   Example: "We use a hexagonal architecture with:
   - TypeScript + NestJS
   - PostgreSQL via Drizzle ORM
   - Redis for caching and queuing
   - Event-driven: we emit domain events via EventEmitter2
   - Error handling: we use Result<T, E> pattern, never throw"

R — Requirements Context
   State explicit requirements, constraints, and edge cases
   Example: "The payment service must:
   - Support idempotent requests (same idempotency-key = same result)
   - Handle concurrent requests for the same user without race conditions
   - Never charge a user twice for the same transaction
   - Return within 3 seconds or timeout gracefully"

C — Compliance Context
   Specify security and regulatory constraints
   Example: "This handles PCI DSS data. Never log card numbers.
   Use the existing VaultService for sensitive data storage.
   All DB queries must be parameterized. Follow OWASP top 10."

H — Helper Patterns
   Reference existing patterns in the codebase
   Example: "Follow the pattern in UserService.createUser()
   for validation and error handling. Use our BaseRepository
   for all database operations."

# With ARCH context, AI writes code that fits your system
# Without context, AI writes generic code that needs heavy modification

# AI-Generated Code Review Checklist

□ SECURITY
  □ No SQL injection (parameterized queries only)
  □ No hardcoded secrets, API keys, or credentials
  □ Authorization checks before every data access
  □ Input validation on all user-supplied data
  □ Sensitive data not logged or exposed in error messages
  □ Cryptographic functions use modern, approved algorithms

□ ARCHITECTURE FIT
  □ Follows established patterns in the codebase
  □ Respects service boundaries (no cross-service DB queries)
  □ Uses established abstractions (BaseRepository, EventBus, etc.)
  □ Error handling follows the project convention

□ RELIABILITY
  □ Network calls have timeouts set
  □ Retries implemented for transient failures
  □ Idempotency keys for non-idempotent operations
  □ Database transactions used where atomicity is required
  □ No unbounded loops that could run forever

□ PERFORMANCE
  □ N+1 queries eliminated (use JOINs or DataLoader)
  □ Database indexes exist for all filtered columns
  □ Large datasets paginated, not fetched all at once
  □ Expensive operations async where possible

□ OBSERVABILITY
  □ Appropriate log levels (info, warn, error)
  □ Correlation IDs propagated through the request
  □ Errors include enough context for debugging
  □ Metrics emitted for critical operations

□ TESTS
  □ Unit tests cover happy path and critical edge cases
  □ Error conditions tested
  □ Mocks don't hide real behavior
  □ Test data doesn't use real user data

// AI Agent System Architecture
// YOU design this — AI cannot design itself into your system

interface AgentSystemDesign {
  // 1. Agent selection: which model for which task?
  modelStrategy: {
    reasoning: 'claude-opus-4-6',    // Complex decisions, costly
    generation: 'claude-sonnet-4-6', // Code/content, balanced
    classification: 'claude-haiku',  // Simple tasks, fast + cheap
  };

  // 2. Reliability: agents hallucinate — design for it
  reliabilityPatterns: [
    'structured-output',    // Force JSON schema, validate before use
    'self-reflection',      // Agent checks its own output
    'human-in-the-loop',    // High-stakes decisions need human review
    'retry-with-variation', // Different prompt on retry
    'fallback-to-human',    // Escalate when confidence is low
  ];

  // 3. Cost control: AI API costs scale with usage
  costControls: [
    'token-budgets',        // Max tokens per request
    'caching',              // Cache identical prompts (semantic cache)
    'prompt-compression',  // Summarize context when too long
    'batch-processing',    // Batch API calls at off-peak hours
  ];

  // 4. Observability: trace every AI call
  observability: [
    'trace-all-llm-calls',  // Log input, output, model, tokens, cost
    'evaluate-output',      // Score outputs against ground truth
    'monitor-costs',        // Alert when spend exceeds threshold
    'detect-regressions',   // Alert when output quality drops
  ];
}

// Key Tools for AI Systems:
// LangChain / LangGraph — Agent orchestration
// LangSmith — LLM observability and evaluation
// OpenTelemetry — Distributed tracing for AI pipelines
// Portkey / Helicone — LLM gateway with cost tracking

# 12-Month AI-Era Software Engineer Roadmap

┌─────────────────────────────────────────────────────────────────┐
│                    12-MONTH ROADMAP TIMELINE                    │
└─────────────────────────────────────────────────────────────────┘

MONTHS 1-2: FOUNDATIONS (AI Workflow + System Design Basics)
  □ Set up your AI workflow (Claude Code + Cursor + Copilot)
  □ Study: System Design Primer (donnemartin/system-design-primer)
  □ Read: "Designing Data-Intensive Applications" by Martin Kleppmann
  □ Practice: Design 5 systems from scratch (design them, then ask AI to review)
  □ Build: A simple API with rate limiting, auth, and caching
  □ Deploy: That API to production with basic observability

MONTHS 3-4: DATA ARCHITECTURE
  □ Learn PostgreSQL deeply: indexes, EXPLAIN ANALYZE, transactions
  □ Set up Redis: sessions, caching, pub/sub, queues
  □ Study: Database internals (how B-trees, WAL, MVCC work)
  □ Practice: Design the data model for a SaaS product from scratch
  □ Build: A CDC pipeline using Debezium
  □ Learn: dbt for data transformation

MONTHS 5-6: MICROSERVICES & DISTRIBUTED SYSTEMS
  □ Study: "Building Microservices" by Sam Newman (free PDF)
  □ Implement: Circuit breaker, retry, bulkhead patterns
  □ Build: Two services that communicate via events (Kafka or RabbitMQ)
  □ Practice: Implement the Saga pattern for a distributed transaction
  □ Deploy: Kubernetes cluster with Helm charts
  □ Set up: Full observability stack (Prometheus + Grafana + Jaeger)

MONTHS 7-8: SECURITY & COMPLIANCE
  □ Study: OWASP Top 10 in depth — find each vulnerability in example code
  □ Complete: OWASP WebGoat (vulnerable-by-design practice app)
  □ Implement: JWT auth with refresh tokens + rotation
  □ Set up: Semgrep in CI/CD for automated security scanning
  □ Study: GDPR requirements as they apply to your current product
  □ Implement: Data deletion pipeline for user data requests

MONTHS 9-10: AI SYSTEMS ENGINEERING
  □ Build: RAG system (document Q&A over your own codebase)
  □ Build: Multi-step AI agent with tool use (file system, APIs)
  □ Implement: LLM observability with LangSmith or Helicone
  □ Study: MCP (Model Context Protocol) — future of AI tool integration
  □ Practice: Cost optimization (caching, batching, model selection)
  □ Build: AI-powered code review bot for your team's PRs

MONTHS 11-12: SYSTEM DESIGN MASTERY
  □ Design: 10 systems end-to-end (Twitter, WhatsApp, Uber, Netflix...)
  □ Write: Architecture Decision Records (ADRs) for each decision
  □ Contribute: To an open-source project you use
  □ Teach: Write an article or give a talk explaining one concept
  □ Build: Your capstone project — a full production system that
             demonstrates all phases of this roadmap

# Capstone Project Ideas (AI-Native Architectures):
# • Multi-tenant SaaS platform with AI-powered features
# • Real-time collaborative editor with AI assistance
# • Event-driven e-commerce with AI recommendation engine
# • Developer productivity tool with LLM integration