Software Engineering Roadmap

# Two Pointers — O(n) instead of naive O(n²)
def has_pair_with_sum(arr: list[int], target: int):
    """Find if any two numbers sum to target. Requires sorted input."""
    left, right = 0, len(arr) - 1
    while left < right:
        total = arr[left] + arr[right]
        if total == target:  return (left, right)
        elif total < target: left += 1
        else:                right -= 1
    return None

# ❌ Opaque — reader must decode every symbol
def f(d, t):
    r = []
    for x in d:
        if x['ts'] > t: r.append(x)
    return r

# ✓ Expressive — reads like a sentence
def filter_recent_events(
    events: list[Event],
    cutoff_timestamp: int
) -> list[Event]:
    """Return events newer than the cutoff timestamp."""
    return [e for e in events if e.timestamp > cutoff_timestamp]

-- Design for your most common queries first
WITH recent_orders AS (
    SELECT customer_id, SUM(total) AS revenue
    FROM orders
    WHERE created_at >= NOW() - INTERVAL '90 days'
      AND status = 'completed'
    GROUP BY customer_id
)
SELECT c.name, c.email, ro.revenue
FROM recent_orders ro
JOIN customers c ON c.id = ro.customer_id
ORDER BY ro.revenue DESC
LIMIT 5;

-- Then: EXPLAIN ANALYZE this. Is it using the index on created_at?

1.  Browser checks DNS cache for IP address
2.  DNS resolution: recursive resolver → root → TLD → authoritative → IP
3.  TCP 3-way handshake (SYN → SYN-ACK → ACK)
4.  TLS handshake: negotiate cipher, exchange certs, derive session keys
5.  Browser sends HTTP GET request
6.  Request hits load balancer → routes to app server
7.  App server processes, queries DB, builds response
8.  HTTP response sent back (200 OK + body)
9.  Browser renders / client parses the response
10. Connection kept alive (HTTP/1.1 keep-alive, HTTP/2 multiplexing)

Know each step. Every one can fail. Every one can be optimized.

# Log investigation — most critical production skill
tail -f /var/log/app/error.log         # live log stream
journalctl -u myapp -n 100             # last 100 lines
grep -A5 -B5 "Exception" app.log       # context around errors

# Disk & network
df -h                                  # full disk = silent failures
ss -tlnp                               # what ports are listening?
curl -v https://api.example.com/health # verbose HTTP check

JUNIOR ENGINEER sees:         SYSTEMS ENGINEER sees:
  "I need to store user data"   "What's the read/write ratio?
                                 How many users? In 2 years?
                                 What's acceptable latency?
                                 What happens when the DB is slow?"

URL SHORTENER — estimating scale
Assumptions: 100M DAU, read:write ratio = 10:1

Writes: 10M/day → 116 writes/sec → 350 peak
Reads:  100M/day → 1,160 reads/sec → 3,500 peak ← hot path
Storage: 18.25B records × 500B = 9TB over 5 years

Conclusions:
  → Reads >> Writes — optimise read path aggressively
  → Cache hot URLs in Redis (expect 90% hit rate)
  → Single DB handles writes; read replicas needed

# The 3 questions for every distributed operation:

# 1. What if the network drops mid-request?
def transfer_right(from_acc, to_acc, amount):
    txn_id = generate_uuid()
    with transaction(txn_id):
        debit(from_acc, amount)
        credit(to_acc, amount)
    # Safe to retry — duplicate txn_id is a no-op

# 2. What if two nodes do the same thing simultaneously?
# Optimistic lock: only succeeds if version matches
UPDATE inventory
   SET qty = :qty, version = version + 1
 WHERE id = :id AND version = :expected_version

# 3. What if a downstream service is slow?
circuit_breaker = CircuitBreaker(
    failure_threshold=5,
    recovery_timeout=30,
    fallback=lambda: cached_response()
)

# Redis caching with stampede protection + TTL jitter
def get_user_profile(user_id: str) -> dict:
    cached = redis.get(f"user:{user_id}")
    if cached: return json.loads(cached)

    lock = redis.set(f"lock:user:{user_id}", "1", nx=True, ex=5)
    if lock:
        try:
            profile = db.query("SELECT * FROM users WHERE id = %s", user_id)
            ttl = 3600 + random.randint(-360, 360)  # jitter prevents mass expiry
            redis.setex(f"user:{user_id}", ttl, json.dumps(profile))
            return profile
        finally:
            redis.delete(f"lock:user:{user_id}")
    else:
        time.sleep(0.1)
        return get_user_profile(user_id)

FROM python:3.12-slim
WORKDIR /app

# Copy deps FIRST — layer caching makes builds 10× faster
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/

# Non-root user — security principle of least privilege
RUN adduser --disabled-password appuser && chown -R appuser /app
USER appuser

EXPOSE 8000
CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

# deployment.yaml — declare desired state, K8s makes it real
apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: myregistry/api:v2.4.1  # never use :latest in production
        resources:
          requests: { memory: "128Mi", cpu: "250m" }
          limits:   { memory: "512Mi", cpu: "500m" }
        readinessProbe:
          httpGet: { path: /health, port: 8000 }
          initialDelaySeconds: 5
        livenessProbe:
          httpGet: { path: /health, port: 8000 }
          failureThreshold: 3

# main.tf — declare your desired cloud infrastructure
terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
  backend "s3" {
    bucket = "my-terraform-state"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_autoscaling_group" "api" {
  min_size         = 2
  max_size         = 10
  desired_capacity = 3
  health_check_type         = "ELB"
  health_check_grace_period = 300
}

resource "aws_budgets_budget" "monthly" {
  budget_type  = "COST"
  limit_amount = "500"
  limit_unit   = "USD"
  time_unit    = "MONTHLY"
  notification {
    comparison_operator = "GREATER_THAN"
    threshold           = 80
    threshold_type      = "PERCENTAGE"
    notification_type   = "ACTUAL"
  }
}

terraform init      # download providers, initialize backend
terraform plan      # preview changes (always review this!)
terraform apply     # make it so
terraform destroy   # tear down (careful in prod!)

# .github/workflows/deploy.yml
name: Test, Build & Deploy
on:
  push:     { branches: [main] }
  pull_request: { branches: [main] }

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt -r requirements-dev.txt
      - run: ruff check src/ tests/
      - run: mypy src/
      - run: pytest tests/unit/ --cov=src

  build:
    needs: test
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build
    environment: production  # requires manual approval in GitHub
    steps:
      - run: |
          kubectl set image deployment/api \
            api=ghcr.io/${{ github.repository }}:${{ github.sha }}
          kubectl rollout status deployment/api --timeout=5m
      - run: curl --fail https://api.myapp.com/health

# AWS Lambda — event-driven, scales to zero
import json, boto3

def handler(event, context):
    bucket = event['Records'][0]['s3']['bucket']['name']
    key    = event['Records'][0]['s3']['object']['key']
    s3     = boto3.client('s3')
    obj    = s3.get_object(Bucket=bucket, Key=key)
    data   = json.loads(obj['Body'].read())
    result = process(data)
    s3.put_object(Bucket=bucket, Key=f"processed/{key}", Body=json.dumps(result))
    return {'statusCode': 200}

A machine learning model is a function:
  f(input) → output + confidence

It was created by:
  optimizer(loss_function(f(training_data), labels)) → parameters

At inference, it's just matrix multiplications + non-linearities.

1. IS AI THE RIGHT TOOL?
   Could a deterministic function solve this instead?
   Spend one week trying rules/heuristics first.

2. WHAT DOES FAILURE LOOK LIKE?
   How does this model fail? How often?
   What happens downstream when it fails?

3. HOW DO I MEASURE SUCCESS?
   What's my evaluation metric?
   How do I know if the model degrades in production?

SUPERVISED:     (input, label) pairs → learn f(input) → label
UNSUPERVISED:   inputs only → find structure / patterns
REINFORCEMENT:  agent + environment + rewards → learn policy
SELF-SUPERVISED: labels from the data itself → GPT, BERT, CLIP

# Every ML training loop is this, at its core:
for epoch in range(num_epochs):
    for batch in dataloader:
        predictions = model(batch.inputs)
        loss = loss_function(predictions, batch.labels)
        loss.backward()       # which params caused the error?
        optimizer.step()      # step in direction that reduces loss
        optimizer.zero_grad()
# BatchNorm, dropout, attention — all improvements on this.

# ❌ Vague prompt — you get vague output
response = llm.complete("Tell me about this code")

# ✓ Structured prompt — clear contract
response = llm.complete("""
You are a senior engineer reviewing a pull request.
Review for: correctness, edge cases, performance, readability.
Output ONLY as JSON:
  { "verdict": "approve|request_changes",
    "issues": [{"severity": "high|medium|low", "description": "..."}],
    "summary": "..." }
Code: {code}
""")

# RAG pipeline in ~30 lines
def rag_query(question: str) -> str:
    # 1. Embed the question
    embedding = openai.embeddings.create(
        input=question, model="text-embedding-3-small"
    ).data[0].embedding

    # 2. Find semantically similar chunks
    results = pinecone_index.query(vector=embedding, top_k=5, include_metadata=True)
    context = "\n\n".join([r.metadata["text"] for r in results.matches])

    # 3. Generate grounded answer
    return openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer based ONLY on the provided context."},
            {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"}
        ]
    ).choices[0].message.content

NOTEBOOK MODEL:               PRODUCTION ML SYSTEM:
  ✓ Runs on your laptop         ✓ Containerised, deployed, versioned
  ✓ Uses static dataset         ✓ Served at low latency
  ✗ Not versioned               ✓ Automatically retrained on fresh data
  ✗ Not monitored               ✓ Monitored for drift and degradation
  ✗ Not reproducible            ✓ Rollback capability

# Detect data drift — the silent model killer
from scipy import stats

def detect_drift(training_dist, production_dist, threshold=0.05):
    _, p_value = stats.ks_2samp(training_dist, production_dist)
    return {
        "drift_detected": p_value < threshold,
        "p_value": p_value,
        "action": "Investigate and consider retraining" if p_value < threshold else "OK"
    }

OWASP Top 5 for LLMs:
1. PROMPT INJECTION       — input hijacks model behaviour
2. INSECURE OUTPUT        — LLM output executed without validation
3. TRAINING DATA POISONING — malicious training data corrupts model
4. MODEL DoS              — crafted inputs cause excessive compute
5. EXCESSIVE AGENCY       — LLM given too many real-world permissions

Fix #5: Principle of least privilege + human-in-the-loop
        for any irreversible action.

Decision: Prompt → RAG → Fine-tune

Does a well-crafted prompt solve it?     YES → Ship it.
Does the model need external knowledge?  YES → Add RAG.
Need specific style / vocabulary?        YES → Consider fine-tuning.
Latency / cost at massive scale?         YES → Fine-tune a smaller model.
Otherwise → Re-examine if you need ML at all.

Code that WORKS:          Code that is CRAFTED:
  ✓ Correct behaviour       ✓ Correct behaviour
  ? Understandable          ✓ Reads like well-written prose
  ? Testable                ✓ Has a test for every behaviour
  ? Changeable              ✓ Easy to extend, hard to break
  ? Maintainable            ✓ Deletes itself as requirements change

# ❌ Opaque — reader must decode every symbol
def proc(d, f, t):
    r = []
    for x in d:
        if x[f] > t: r.append(x)
    return r

# ✓ Expressive — reads like a sentence
def filter_records_above_threshold(
    records: list[dict],
    field: str,
    threshold: float
) -> list[dict]:
    return [r for r in records if r[field] > threshold]

# ❌ One function doing five things — impossible to test or reuse
def process_order(order):
    if not order.items: raise ValueError("Empty order")
    if order.user.is_premium: order.total *= 0.9
    charge = stripe.charge(order.total, order.user.card)
    send_email(order.user.email, f"Order {order.id} confirmed")
    db.save(order)
    return order

# ✓ Each function has one job — independently testable
def process_order(order: Order) -> Order:
    validate_order(order)
    apply_discount(order)
    charge_payment(order)
    notify_user(order)
    persist_order(order)
    return order

# TDD: write the test FIRST — design emerges from tests

# Step 1 (RED): write failing test
def test_calculate_tax_raises_on_negative():
    with pytest.raises(ValueError):
        calculate_tax(-100, 0.2)  # function doesn't exist yet

# Step 2 (GREEN): write minimum code to pass
def calculate_tax(amount: float, rate: float) -> float:
    if amount < 0:
        raise ValueError("Amount cannot be negative")
    return amount * rate

# Step 3 (REFACTOR): clean up while keeping tests green

# ❌ Arrow anti-pattern — hard to reason about
def process_payment(user, order):
    if user is not None:
        if user.is_active:
            if order.total > 0:
                if user.has_payment_method:
                    charge(user, order)

# ✓ Guard clauses — happy path is unobscured
def process_payment(user, order):
    if user is None:               raise UserNotFound()
    if not user.is_active:         raise InactiveUser()
    if order.total <= 0:           raise EmptyOrder()
    if not user.has_payment_method: raise NoPaymentMethod()
    charge(user, order)

REST Principles:
  Use nouns, not verbs:   /users not /getUsers
  HTTP verbs carry meaning: GET=read, POST=create, PATCH=update, DELETE=remove
  Pluralise consistently: /users, /orders, /products
  Version from day one:   /v1/users
  Return correct status:  201 Created, 404 Not Found, 422 Unprocessable

Well-designed error response:
  HTTP 422
  {
    "error": {
      "code": "VALIDATION_FAILED",
      "message": "Request validation failed",
      "details": [
        { "field": "email", "code": "INVALID_FORMAT",
          "message": "Must be a valid email address" }
      ],
      "request_id": "req_abc123"
    }
  }

Your code will be read by ~5 engineers over its lifetime.
Your design doc will shape decisions for 50 engineers.
Your RFC will influence architecture used by 500 users.
Your talk will change how 5,000 people think about a problem.

Communication has leverage. Code has limits.

# RFC-042: Replace synchronous email sending with async queue

## Status
PROPOSED | 2024-01-15 | Author: @yourname

## Problem
Our checkout endpoint has a p99 latency of 2,400ms.
Profiling shows 1,800ms is waiting for SendGrid API calls.

## Proposed Solution
Replace synchronous email sending with a job queue:
  1. Checkout writes email job to Redis queue (< 5ms)
  2. Worker pool processes jobs asynchronously
  3. Retry with exponential backoff on failure

## Alternatives Considered
A. Use SendGrid's batch API — rejected: doesn't fix latency issue
B. Move emails to Lambda — rejected: adds cold start complexity

## Impact
- Expected p99 improvement: 2,400ms → 600ms
- Email delivery delay: 0ms → < 5 seconds (acceptable per PM)
- Risk: email failures become silent — need alerting

## Open Questions
1. Should we track email job status in the DB for support queries?

# ADR-017: Use PostgreSQL for primary data store

## Date: 2024-01-10 | Status: Accepted

## Context
Relational data (users → orders → items), complex reporting,
small team (3 engineers), financial operations requiring ACID.

## Decision
PostgreSQL 16 as primary data store.

## Rationale
- Relational data — joins are frequent, not an afterthought
- Team has strong SQL expertise — no learning curve
- JSONB covers flexible-schema edge cases

## Revisit When
- User count exceeds 5M AND write QPS exceeds 5,000

BEFORE WRITING A SINGLE SLIDE, ANSWER:

Who is in the room?
  Engineers only → go deep on implementation
  Mixed → lead with impact, details later
  Executives → business outcome, skip implementation

What do you need them to DO after?
  Approve a proposal → give them the decision, not the journey
  Understand a system → give them the mental model, not the code

sequenceDiagram
    participant U as User
    participant A as API Gateway
    participant S as Auth Service
    participant D as Database

    U->>A: POST /checkout (JWT token)
    A->>S: Validate token
    S-->>A: User ID + permissions
    A->>D: Begin transaction
    A->>D: Deduct inventory + Create order
    D-->>A: Order ID
    A-->>U: 201 Created {order_id}

BLOCKING:    Must change before merge — bug, security issue, contract break
SUGGESTION:  Strong recommendation — SRP violation, missing test coverage
NIT:         Take it or leave it — style, naming preference

Always label your feedback. The author needs to know the stakes.

THE THREE THINGS STAKEHOLDERS ALWAYS WANT TO KNOW:

1. WHAT IS THE IMPACT?
   "We reduced checkout latency by 75%"
   → "This is expected to improve conversion by ~2%, worth ~$400K/year"

2. WHAT ARE THE RISKS?
   Be specific about worst case. Quantify it.

3. WHAT DO YOU NEED FROM ME?
   "I need your approval to proceed by Friday."
   Never leave the meeting without a clear ask.

GOOD: "We discovered a migration issue that will delay launch by one week.
      Here are three options: A, B, C. We recommend B. Here's why."

BAD:  [Silence until two days before launch]
      "We have a problem. We need two more weeks."

THE RULE: Surface problems the day you discover them.
          Come with options, not just problems.

THE LADDER OF DISAGREEMENT:

1. Raise the concern clearly, once, with evidence
2. Make sure you're heard: "Do you understand my concern about X?"
3. Propose an alternative with reasoning
4. Accept the decision and commit fully

WHAT NOT TO DO:
  ✗ Passive resistance after the decision is made
  ✗ Endless rehashing
  ✗ "I told you so" when it goes wrong
  ✗ Going around the decision-maker

FORMAT FOR A 45-MIN LUNCH & LEARN:
  5 min  — Why this matters (motivation, not just content)
  10 min — Core concept with concrete example
  10 min — Live demo or code walkthrough
  10 min — "What would you do if..." scenarios
  10 min — Q&A / discussion

RULES:
  No slides without code or diagrams
  Pause every 10 minutes and ask a question
  End with: "What's one thing you'll try this week?"
  Write a 1-page summary and share it afterwards