Documentation Index

Fetch the complete documentation index at: https://resources.devweekends.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Legacy Modernization & Technical Strategy

​

Part I — Legacy System Modernization

​

1.1 Understanding Legacy Systems

​

1.2 The Strangler Fig Pattern — In Depth

1. Continuous delivery of value. The business never stops. You are not asking for 18 months of zero feature development while you rewrite.
2. Incremental risk. Each migration step is small and reversible. If the new service has a bug, roll back that one route — not the entire system.
3. Learning as you go. You discover the legacy system’s hidden behaviors incrementally, not all at once.
4. Parallel operation. Old and new systems coexist. You can compare their behavior. You build confidence through evidence, not hope.

# Initial state: all traffic to monolith
/api/users/*     -> monolith:8080
/api/orders/*    -> monolith:8080
/api/products/*  -> monolith:8080
/api/payments/*  -> monolith:8080

​

1.3 Big Bang Rewrites vs Incremental Migration

1. The Second System Effect (Fred Brooks, 1975). The rewrite team, freed from the constraints of the legacy system, over-designs everything. “While we are at it, let us also…” Every stakeholder adds requirements. The scope balloons.
2. Feature parity is a moving target. The legacy system is still shipping features while you rewrite. By the time the rewrite is “done,” the legacy system has evolved. You are chasing a moving target.
3. Invisible requirements. The legacy system handles thousands of edge cases that are not documented anywhere — they are embedded in conditional logic, database triggers, and operational runbooks. The rewrite team discovers them one by one, usually in production.
4. Political death spiral. The rewrite takes longer than estimated (they always do). Stakeholders lose confidence. Budget gets cut. The rewrite team is pressured to ship before it is ready. They ship something half-baked. Users complain. The rewrite is declared a failure.
5. Lost institutional knowledge. The engineers who understood the legacy system’s behavior either leave during the long rewrite or are not consulted by the rewrite team who assume they can do better.

• The tech stack is truly dead — no community, no security patches, no hiring pool (e.g., PowerBuilder, Silverlight).
• The architecture is fundamentally incompatible with a non-negotiable business requirement (e.g., single-tenant to multi-tenant for SaaS transition).
• The codebase is small enough to rewrite in 3-6 months with a small team.
• The system has comprehensive behavioral tests that can validate the rewrite.

​

1.4 Anti-Corruption Layers

• Translates between the legacy system’s domain model and your new system’s domain model.
• Maps legacy data formats to your canonical formats.
• Handles the legacy system’s idiosyncrasies (nullable fields that should not be nullable, overloaded enums, stringly-typed data).
• Provides a stable interface even when the legacy system changes.

# Anti-corruption layer: translates legacy customer model
class LegacyCustomerAdapter:
    STATUS_MAP = {
        "A": CustomerStatus.ACTIVE,
        "I": CustomerStatus.INACTIVE,
        "D": CustomerStatus.DELETED,
        "S": CustomerStatus.SUSPENDED,
    }

    def translate(self, legacy_response: dict) -> Customer:
        return Customer(
            id=str(legacy_response["CUST_ID"]),  # Legacy uses integer IDs
            name=legacy_response["CUST_NM"].strip(),  # Legacy pads with spaces
            email=legacy_response["EMAIL_ADDR"].lower(),
            status=self.STATUS_MAP.get(
                legacy_response["CUST_STAT"],
                CustomerStatus.UNKNOWN  # Defensive: handle unexpected values
            ),
            created_at=self._parse_legacy_date(legacy_response["CRT_DT"]),
        )

    def _parse_legacy_date(self, legacy_date: str) -> datetime:
        # Legacy system uses YYYYMMDD format as a string, not ISO 8601
        return datetime.strptime(legacy_date, "%Y%m%d")

​

1.5 Monolith to Microservices

​

When to Decompose (and When NOT To)

1. Organizational scaling pain. Multiple teams (15+ engineers) stepping on each other. Merge conflicts in the same files. Deployment coordination across teams. This is the primary driver — microservices are an organizational scaling solution.
2. Well-understood domain boundaries. You have operated the monolith long enough to know where the natural seams are. If you cannot draw the bounded contexts on a whiteboard and get agreement from the team, you are not ready.
3. Infrastructure maturity. You have (or can build) CI/CD pipelines, container orchestration, service discovery, distributed tracing, and centralized logging. Without this, each microservice becomes an operational island.
4. A concrete, measurable problem. “We want microservices” is not a reason. “Our checkout team cannot deploy independently because the recommendation engine shares the same deployment unit, and this has delayed 12 releases in the last quarter” is a reason.

• Team is fewer than 15 engineers. The coordination overhead of microservices exceeds the coordination overhead of a monolith at this size.
• The domain is still being discovered. If feature requirements change every sprint, microservice boundaries drawn today will be wrong next month.
• You are doing it for the technology. “Microservices are best practice” is not a reason. Neither is “everyone else is doing it” or “it will look good on our resumes.”
• You do not have platform engineering capacity. Someone has to build and maintain the service mesh, the deployment pipelines, the tracing infrastructure. If that someone does not exist, you are signing up for operational chaos.

​

Domain-Driven Design as a Decomposition Guide

• Shared Kernel — Two contexts share a common model. Tightly coupled. Changes require coordination.
• Customer-Supplier — One context (upstream) provides data to another (downstream). The upstream context’s model shapes the downstream context’s integration.
• Anti-Corruption Layer — The downstream context refuses to let the upstream model leak in and translates at the boundary.
• Conformist — The downstream context accepts the upstream model as-is. Fastest to implement, creates coupling.

1. Talk to domain experts. Engineers, product managers, customer support — anyone who understands the business. Ask: “When you say ‘order,’ what do you mean?” Different people will give different answers. Those different answers are bounded context clues.
2. Analyze the code. Look for clusters of classes/modules that change together (use git log to find co-change patterns). Look for classes with the same name but different meanings in different packages. Look for data models that are shared across unrelated features.
3. Map the communication patterns. Which parts of the system call which other parts? Draw the dependency graph. Tight clusters with few external dependencies are natural service candidates.
4. Identify the data ownership. Which tables are written by which code paths? If a table is written by multiple unrelated features, that table is likely a shared concern that needs to be decomposed.

​

The Modular Monolith as a Middle Ground

1. Define module boundaries aligned with bounded contexts.
2. Enforce boundaries with static analysis (Packwerk for Ruby, ArchUnit for Java, custom ESLint rules for TypeScript, Go’s internal packages).
3. Each module owns its data — separate database schemas or at minimum separate tables with no cross-module joins.
4. Modules communicate through defined interfaces — public API surfaces, not direct database reads or internal class access.
5. Test at the module boundary — integration tests verify that a module’s public API behaves correctly, not its internal implementation.

​

Service Extraction Patterns

1. Create an interface for the functionality being extracted.
2. The monolith uses the interface, initially backed by the existing in-process implementation.
3. Build the new service implementing the same interface.
4. Create a client adapter that calls the new service over the network.
5. Swap the implementation behind the interface from in-process to remote client.
6. Feature flag the swap so you can toggle between implementations.

1. Build the new service.
2. For every request, call both the monolith and the new service.
3. Return the monolith’s response to the user.
4. Compare both responses asynchronously. Log discrepancies.
5. Once discrepancy rate drops below threshold, switch to returning the new service’s response.

1. The monolith starts publishing domain events when state changes (e.g., OrderCreated, OrderShipped).
2. The new service subscribes to these events and builds its own read model.
3. Gradually, read traffic shifts to the new service.
4. Eventually, write traffic shifts too, and the new service becomes the authority.

​

Database Decomposition Strategies

​

1.6 Migration Patterns

​

Parallel Run (Shadow Traffic)

# Simplified parallel run at the routing layer
async def handle_request(request):
    # Primary: legacy system (serves the user)
    primary_response = await legacy_system.handle(request)

    # Secondary: new system (shadow, does not affect user)
    try:
        shadow_response = await asyncio.wait_for(
            new_system.handle(request),
            timeout=5.0  # Don't let shadow traffic slow primary
        )
        compare_responses(primary_response, shadow_response, request)
    except Exception as e:
        log_shadow_error(e, request)

    return primary_response  # Always return legacy response

def compare_responses(primary, shadow, request):
    if primary.status_code != shadow.status_code:
        log_discrepancy("status_code", primary, shadow, request)
    if normalize(primary.body) != normalize(shadow.body):
        log_discrepancy("body", primary, shadow, request)
    if abs(primary.latency - shadow.latency) > LATENCY_THRESHOLD:
        log_discrepancy("latency", primary, shadow, request)

• Shadow traffic must not cause side effects. If the new system writes to a database or calls external APIs, those writes must go to a separate environment or be no-ops.
• Shadow traffic adds load. Your new system must handle production-scale traffic even though it is not serving users.
• Response comparison must be tolerant of acceptable differences (timestamps, generated IDs, ordering of unordered collections).
• Track discrepancy rates over time. You are looking for a downward trend to zero, not perfection on day one.

​

Parallel-Run Telemetry

1. Overall match rate — the headline number. Target: 99.9%+ before considering cutover. Display as a time-series chart so you can see the trend.
2. Match rate by endpoint — some endpoints will reach parity faster than others. This tells you where to focus debugging effort.
3. Match rate by request category — mismatches often cluster around specific user types, data shapes, or edge cases (e.g., accounts created before a specific migration, international addresses, currency edge cases).
4. Latency comparison distribution — a histogram of latency deltas. You want the new system to be within 10% of the legacy system’s latency at p99. If the new system is consistently slower, investigate before cutover.
5. New system error rate — errors that the new system throws but the legacy system does not. These are bugs, not discrepancies. Track separately.
6. Discrepancy trend — the most important chart. Is the mismatch rate going down over time? A flat or rising trend means the team is not making progress on root causes.

​

Cutoff Criteria — When to Stop the Parallel Run

• The mismatch rate has plateaued above 1% for 4+ weeks with no root cause identified. This suggests a fundamental behavioral difference between the systems that may require re-architecting the new system.
• The parallel run is consuming more than 30% of the team’s capacity in discrepancy investigation. You are spending more time debugging the comparison than building the new system.
• The legacy system’s behavior is changing faster than the new system can keep up (active feature development on the legacy system during migration). Consider pausing feature development on the affected area.

​

Sunset Plans — Decommissioning the Legacy System

​

Incremental Cutover with Feature Flags

# Feature flag-based routing
def route_request(request, user):
    if feature_flags.is_enabled("new-order-service", user):
        return new_order_service.handle(request)
    else:
        return legacy_order_service.handle(request)

1. Internal users only (dogfooding). Your team uses the new system. Find obvious bugs.
2. Beta users who opted in. Power users who will report issues.
3. 1% of traffic randomly. Monitor error rates.
4. 10% -> 25% -> 50% -> 100% with hold periods at each stage.

​

Rollback Planning

• Can we route 100% of traffic back to the legacy system in under 5 minutes?
• If we roll back, is the data in the legacy system still consistent? (Were writes going to both systems, or only the new one?)
• Have we tested the rollback procedure? (Not “we believe it works” — “we have executed it in staging.”)
• Who has authority to trigger the rollback? (On-call engineer? Migration lead? VP?)
• What are the metrics that trigger an automatic rollback? (Error rate > X? Latency > Y?)

​

Success Metrics for Migrations

​

1.7 Language and Framework Migrations

​

When Language Migration Is Justified

• End of life. Python 2 reached EOL in January 2020. No more security patches. This is the clearest justification — you are taking on unmitigated security risk.
• Performance ceiling. You have optimized everything you can in the current language and still cannot meet performance requirements. You have profiled, you have benchmarked, you have tried algorithmic improvements. The language runtime itself is the bottleneck.
• Hiring impossibility. You cannot hire engineers for the current stack. If your system is in a niche language with a tiny talent pool, the bus factor risk is existential.
• Ecosystem death. The framework or runtime has no active community, no security patches, and no path forward.

• “The new language is faster.” (Are your bottlenecks actually CPU-bound? Have you profiled?)
• “Everyone is using Go/Rust/TypeScript now.” (Resume-driven development.)
• “Our code is messy.” (A rewrite in a new language will be messy too if you do not address the underlying design problems.)
• “Developers want to learn something new.” (Legitimate for team morale, but not sufficient on its own. Channel this energy into side projects, not core system migrations.)

​

Real-World Language Migration Examples

• Why it happened: Python 2 EOL forced the issue. Libraries stopped supporting Python 2.
• Key challenge: str vs bytes semantics changed fundamentally. Code that worked with implicit ASCII assumptions broke with Unicode.
• Migration strategy: Use 2to3 automated tool for the easy syntactic changes. Use python-future or six for bridging libraries. Migrate module by module, running tests at each step. The hardest part is third-party libraries — you cannot migrate faster than your dependencies.
• Lesson: Automated tooling handles 60-70% of the work. The remaining 30-40% is the hard part: behavioral changes in string handling, integer division, and dictionary iteration ordering.

• Why it happens: Java 8 is approaching end of free public updates. Modern Java (17+) offers records, sealed classes, pattern matching, and significant performance improvements (ZGC, virtual threads).
• Key challenge: Module system (JPMS) introduced in Java 9 breaks libraries that use internal APIs via reflection. Many enterprise libraries needed major version bumps.
• Migration strategy: Skip intermediate versions — go from 8 to the latest LTS (21 as of this writing). Use jdeps to identify dependencies on internal APIs. Update dependencies first, then the JDK version. Use --add-opens flags as a temporary bridge for libraries that have not been updated.

• Key challenge: Not just a library swap — it is a paradigm shift from opinionated framework (Angular’s dependency injection, RxJS, TypeScript-first) to library ecosystem (React’s composition model, hooks, choice of state management).
• Migration strategy: Micro-frontend architecture. New pages/features are built in React. Existing Angular pages stay until they need significant changes, then are rebuilt in React. A shell application mounts both Angular and React components. Use Module Federation (webpack 5) or single-spa for runtime composition.
• Lesson: UI migrations are inherently incremental because pages are naturally isolated. Do not try to convert component by component within a page — convert page by page.

• Why it sometimes happens: Rails is productive for building features quickly but can hit performance walls at very high concurrency. Go offers better CPU utilization, lower memory footprint, and native concurrency.
• Key challenge: You lose Rails’ massive ecosystem — ORM, migrations, background jobs, mailer, asset pipeline. Each must be replaced with a Go equivalent or a SaaS tool.
• Migration strategy: Extract the hottest path (the API endpoint handling the most traffic) first. Build it in Go behind the routing layer. Leave Rails handling everything else. Incrementally extract more paths as justified by performance data.
• Lesson: Most teams that “migrate to Go” end up with a polyglot system — Go for performance-critical services, Rails (or Python) for admin tools and low-traffic endpoints. This is fine. Polyglot is not a failure — it is pragmatism.

​

Interop Strategies During Migration

1. Shared API contracts. Both systems expose the same API. Use OpenAPI/Swagger specs as the single source of truth. Generate client libraries for both languages from the spec.
2. Shared database with read replicas. The old system remains the write authority. The new system reads from a replica. Gradually shift write authority.
3. Event bus. Both systems publish and subscribe to the same event stream. This decouples their lifecycles while keeping data consistent.
4. Shared authentication. Use a centralized auth service (or external provider like Auth0) that both systems trust. Do not maintain two auth systems.

​

Part II — Technical Debt Management

​

2.1 Technical Debt Taxonomy

​

Martin Fowler’s Technical Debt Quadrant

​

Quantifying Technical Debt

​

2.2 Debt Prioritization Frameworks

​

RICE Scoring for Tech Debt

• Refactoring the authentication module: Reach = 8 (every engineer authenticates), Impact = 2 (causes bugs weekly), Confidence = 90%, Effort = 3 weeks. Score = (8 x 2 x 0.9) / 3 = 4.8
• Upgrading the logging library: Reach = 15 (entire team), Impact = 0.5 (minor annoyance), Confidence = 100%, Effort = 1 week. Score = (15 x 0.5 x 1.0) / 1 = 7.5

​

Impact Mapping

Business Goal: Reduce checkout latency to under 2 seconds
  → Requires: Optimizing the order processing pipeline
    → Blocked by: Synchronous payment processing (tech debt)
    → Blocked by: N+1 database queries in cart calculation (tech debt)
    → Blocked by: No caching layer for product catalog (tech debt)

​

Negotiating Tech Debt Paydown with Product Managers

1. Tie debt to velocity. “Last quarter, our average feature delivery time was 3 weeks. 40% of that time was spent working around the legacy payment module. If we spend 2 weeks refactoring it, we project a 25% reduction in feature delivery time for the next 2 quarters.”
2. Tie debt to incidents. “The order processing module caused 7 incidents last quarter, each costing approximately 4 hours of engineering time plus estimated revenue loss. Refactoring the retry logic would eliminate the class of bugs causing 5 of those 7 incidents.”
3. Bundle debt with features. “This feature requires changes to the user service. While we are in there, we can pay down the 3 outstanding debt items. The incremental cost is 2 days on top of the 2-week feature — a 10% investment for a 30% reduction in future development time in that area.”
4. The 20% rule. Reserve 20% of sprint capacity for tech debt, permanently. This is not negotiable because it is not a one-time investment — it is ongoing maintenance. Frame it like building maintenance: you do not ask permission to fix the roof. You budget for it.
5. Debt walls and debt sprints. Make debt visible. Create a “tech debt wall” — a physical or virtual board showing the top 10 debt items, their business impact, and their estimated fix cost. Run a quarterly “debt sprint” where the team spends one full sprint on nothing but debt paydown.

​

2.3 Code Modernization

​

Refactoring at Scale

// Before: legacy API
import { oldFetch } from 'legacy-http';
const data = await oldFetch('/api/users', { retries: 3 });

// After: new API (applied by codemod across 500 files)
import { httpClient } from '@company/http';
const data = await httpClient.get('/api/users', { retryPolicy: 'standard' });

​

Automated Code Quality Gates

• Linting rules that enforce code standards. If you are migrating away from an old pattern, create a lint rule that flags it in new code.
• Complexity thresholds in CI. Fail the build if cyclomatic complexity exceeds a threshold. Tools: SonarQube, CodeClimate, ESLint complexity rules.
• Dependency checks in CI. Fail the build if a new dependency is added without approval. Tools: Renovate, Dependabot (for automated updates), Snyk (for vulnerability scanning).
• Architecture fitness functions. Automated tests that verify architectural constraints. Example: “No module in the payments package may import from the marketing package.” Tools: ArchUnit (Java), Packwerk (Ruby), custom scripts.

​

Testing Legacy Code

# Characterization test: we don't know what the "right" answer is,
# but we know what the system currently returns
def test_calculate_shipping_characterization():
    # This test documents current behavior, not desired behavior
    result = legacy_shipping_calculator.calculate(
        weight=5.0, destination="CA", expedited=True
    )
    # The system returns 23.47 -- we don't know if this is "correct"
    # but if it changes after refactoring, we want to know
    assert result == 23.47

1. Write characterization tests around the code you are about to change. Cover the happy paths and the most common edge cases.
2. Use approval tests for complex output.
3. Introduce seams — points in the code where you can intercept behavior for testing. Michael Feathers’ Working Effectively with Legacy Code is the definitive guide to this technique.
4. Refactor under the safety net. Make small changes. Run tests after each change. Never refactor and change behavior in the same commit.

​

Part III — Technology Evaluation & Strategy

​

3.1 Build vs Buy

​

The Framework for Evaluation

​

Hidden Costs of Buy

1. Vendor lock-in. Switching costs increase over time. Once your data is in the vendor’s format, your workflows depend on their APIs, and your team’s skills are specific to their platform, moving away requires a migration project.
2. API limitations. The vendor’s API does 80% of what you need. The other 20% requires workarounds that become the most fragile, hardest-to-maintain parts of your codebase.
3. Pricing changes. Vendors change pricing. Sometimes dramatically. If your business depends on their pricing staying stable, you are exposed. Twilio raised prices. Heroku eliminated their free tier. AWS changes pricing structures regularly.
4. Performance ceiling. The vendor optimizes for the median customer. If your use case is at the 99th percentile, you may hit performance limits that the vendor has no incentive to fix.
5. Security and compliance. You are still responsible for your users’ data, even when a vendor handles it. Vendor breaches become your breaches. Vendor compliance gaps become your compliance gaps.
6. Integration maintenance. Vendors update their APIs. Sometimes with breaking changes. You need to maintain the integration layer indefinitely.

​

Hidden Costs of Build

1. Ongoing maintenance. The feature is shipped, but now you maintain it forever. Security patches, dependency updates, bug fixes, performance optimization — all on you.
2. Opportunity cost. Every engineer building internal tools is an engineer not building product features. The opportunity cost of build is the features you did not ship.
3. Security burden. If you build your own auth system, you own every security vulnerability. If you build your own payment processing, you own PCI compliance. These are deep, specialized domains.
4. Hiring and knowledge transfer. Custom systems require custom knowledge. When the engineer who built it leaves, you have a legacy system problem.
5. Feature creep. Once you build it, internal stakeholders request features. “Since we own the auth system, can we add SSO? SAML? SCIM? MFA?” Each addition increases scope and maintenance burden.

​

3.2 Vendor Evaluation

​

Systematic Evaluation Framework

​

TCO Calculation Beyond License Costs

​

Open Source vs Commercial

​

3.3 Technology Radar

​

How to Evaluate New Technologies for Your Organization

​

Building an Internal Tech Radar

1. Quarterly review. Every quarter, the engineering leadership (tech leads, staff engineers, architecture team) reviews the radar. Technologies move between rings based on real experience, not hype.
2. Evidence-based movement. To move a technology from Assess to Trial, someone must have run a proof of concept and written up the results. To move from Trial to Adopt, someone must have used it in a production project and documented the operational experience.
3. Hold is not punishment. Hold means “we have decided not to invest further in this.” It might be a great technology that does not fit your context. It might be a technology that has been superseded by a better option. Document the reason.
4. Publish it internally. The radar should be visible to every engineer. It answers the question “can I use X in my project?” without requiring a meeting. Reduce decision fatigue.

​

Avoiding Resume-Driven Development

1. Hack weeks/20% time. Let engineers experiment with new technologies in bounded environments.
2. Internal tech talks. Engineers who explore new technologies share findings with the team. This satisfies the learning urge without production risk.
3. Proof of concept budget. Allocate 1-2 sprints per quarter for PoC work on technologies in the Assess ring. Structured experimentation is healthy.
4. Career growth conversations. Help engineers understand that “I introduced 3 new technologies” is not a promotion case. “I migrated our payment processing to a new architecture that reduced incident rate by 60%” is.

​

Part IV — Business Acumen for Engineers

​

4.1 Understanding Business Context

​

P&L Basics for Engineers

​

How Engineering Decisions Affect Unit Economics

• CAC (Customer Acquisition Cost): How much it costs to acquire one customer. Engineering affects this through conversion rate optimization, performance (faster pages convert better), and reliability (downtime during a marketing campaign wastes ad spend).
• LTV (Lifetime Value): How much revenue one customer generates over their lifetime. Engineering affects this through reliability (uptime), feature quality (engagement), and performance (user experience).
• LTV/CAC ratio: Should be greater than 3 for a healthy SaaS business. If it is less than 1, you are losing money on every customer.
• Gross margin per user: Revenue per user minus infrastructure cost per user. Cloud cost optimization directly improves this.

​

Revenue-Generating vs Cost-Center Engineering

• “Our platform team’s CI/CD improvements reduced deployment time from 45 minutes to 8 minutes, allowing product teams to deploy 3x more frequently. This directly accelerated the shipping of 15 revenue features last quarter.”
• “Infrastructure cost optimization reduced our cloud bill by $180k/month. That is$2.16 million annually — equivalent to hiring 10 additional engineers.”
• “The observability platform we built reduced mean time to detection from 15 minutes to 2 minutes. Last quarter, this prevented an estimated 4 hours of downtime that would have cost $320k in lost revenue.”

​

Infrastructure Cost Optimization as a Profit Lever

1. Right-sizing. Most instances are over-provisioned. Use cloud provider tools (AWS Compute Optimizer, GCP Recommender) to identify instances running at 10% CPU utilization.
2. Reserved instances / savings plans. For predictable workloads, commit to 1-3 year terms for 30-60% savings.
3. Spot/preemptible instances. For fault-tolerant workloads (batch processing, CI/CD), use spot instances for 60-90% savings.
4. Storage lifecycle policies. Move infrequently accessed data to cheaper storage tiers. S3 Standard vs S3 Glacier is a 90%+ cost difference.
5. Idle resource cleanup. Development and staging environments running 24/7 when they are only used during business hours. Schedule them to auto-stop.

​

4.2 Communicating Technical Decisions

​

Writing Effective RFCs and ADRs

# RFC: [Title]

## Status: [Draft | In Review | Accepted | Rejected | Superseded]
## Author: [Name]
## Date: [Date]
## Reviewers: [Names]

## Summary
One paragraph. What are you proposing and why?

## Motivation
What problem does this solve? Who is affected?
What happens if we do nothing?

## Detailed Design
How will this work? Be specific.
Include diagrams, API contracts, data models.

## Alternatives Considered
What other approaches did you evaluate?
Why did you reject them?

## Risks and Mitigations
What could go wrong? How do we detect it?
What is the rollback plan?

## Migration Plan
How do we get from here to there?
What is the timeline?
What is the incremental path?

## Success Metrics
How do we know this worked?
What do we measure and when?

## Open Questions
What have you not figured out yet?
What input do you need from reviewers?

# ADR-001: Use PostgreSQL for primary data store

## Status: Accepted
## Date: 2024-03-15

## Context
We need a primary database for our e-commerce platform.
We expect 10,000 transactions per day initially, growing to
100,000 within 2 years. We have strong SQL expertise on the
team. We need ACID transactions for payment processing.

## Decision
We will use PostgreSQL (managed, via AWS RDS) as our
primary data store.

## Consequences
- We get strong consistency, mature tooling, and a large
  talent pool.
- We accept that single-node PostgreSQL has a scaling ceiling
  around 10TB / 50,000 TPS. If we hit this, we will evaluate
  Citus or Aurora PostgreSQL.
- We commit to the SQL data model. NoSQL flexibility is
  traded for query power and consistency guarantees.

​

Presenting Technical Strategy to Non-Technical Stakeholders

1. Business impact. Not “we are migrating to Kubernetes” but “we are reducing deployment time from 2 hours to 15 minutes, which will let us ship features 3x faster.”
2. Timeline and milestones. Not “it will take a while” but “Phase 1 completes by Q2, Phase 2 by Q4. You will see measurable improvement in deployment frequency by the end of Q2.”
3. Risk. Not “it is low risk” but “the main risk is data migration. We mitigate it by running both systems in parallel for 4 weeks and having a one-click rollback.”
4. Cost. Not “we need more engineers” but “this requires 3 engineers for 4 months. The projected ROI is $1.2M in annual infrastructure savings.”

1. The problem (in business terms, with data).
2. The proposal (what you will do, when, and what success looks like).
3. The ask (what you need from leadership — budget, headcount, timeline commitment).

​

Quantifying Engineering Impact in Business Terms

​

4.3 Engineering Strategy

​

Conway’s Law and Team Topology

​

Platform vs Product Engineering Investment Split

• Startup (< 20 engineers): 90% product, 10% platform. Ship features. Use managed services. Do not build internal tools.
• Growth (20-100 engineers): 80% product, 20% platform. Invest in CI/CD, developer experience, shared libraries, internal APIs.
• Scale (100-500 engineers): 70% product, 30% platform. Build internal platforms, service mesh, developer portals, cost optimization tools.
• Enterprise (500+ engineers): 65% product, 35% platform. Mature platform engineering organization. Internal developer platform as a product.

​

Technology Standardization vs Team Autonomy

​

Part V — Cloud Migration & System Design

​

5.1 Cloud Migration Strategies

​

The 7 Rs of Cloud Migration

​

Lift-and-Shift vs Cloud-Native

1. Phase 1: Rehost/Replatform (3-6 months). Get out of the data center. Move to VMs with managed databases. Establish cloud operations, monitoring, and security baseline. This creates urgency to close the data center (cost savings) and builds cloud skills on the team.
2. Phase 2: Refactor (12-24 months). Now that you are in the cloud, incrementally refactor to cloud-native architecture. Containerize services. Adopt managed services. Implement auto-scaling. This is where the real value comes — but it requires cloud-native skills that the team built in Phase 1.

​

Multi-Cloud Strategy

• Regulatory compliance. Some industries require data to be processable by multiple independent providers (financial services, government).
• Negotiation leverage. Having a credible ability to run on multiple clouds gives you pricing leverage with each provider.
• Best-of-breed services. GCP for ML (BigQuery, Vertex AI), AWS for general infrastructure, Azure for Microsoft ecosystem integration.
• Disaster recovery. If one cloud provider has a major outage, you can fail over to another. (Though in practice, the blast radius of a single-cloud outage is usually smaller than the complexity cost of multi-cloud.)

• Small to mid-size companies. The operational overhead of managing two cloud providers (two sets of IAM, two monitoring systems, two networking models) exceeds any benefit for teams under 50-100 engineers.
• “Just in case.” Multi-cloud as an insurance policy is expensive insurance. You are paying 30-50% more in operational complexity for an event (total cloud provider failure) that has never happened.
• Avoiding lock-in for its own sake. Using only cloud-agnostic services (Kubernetes, PostgreSQL, Redis) across multiple clouds means you are paying cloud prices for commodity infrastructure while forgoing the managed services that are the primary value of cloud.

​

Cloud Cost Modeling and Showback/Chargeback

1. Tag everything. Every cloud resource must have tags: team, environment, service, cost-center. Enforce tagging through CI/CD (fail deploys without required tags).
2. Dashboard per team. Show daily cloud spend broken down by service. Trend lines. Budget vs actual.
3. Anomaly alerting. Alert when a team’s spend spikes more than 20% above the rolling average. This catches runaway resources before the monthly bill arrives.
4. Optimization recommendations. Automated suggestions: “Team X has 15 EC2 instances at < 5% CPU utilization. Recommended action: right-size or terminate.”

​

Migration Sequencing

1. First: Low-risk, loosely-coupled applications. Internal tools, dev environments. Build migration skills and playbooks on systems where mistakes are cheap.
2. Second: Medium-risk applications with clear cloud benefits. Batch processing (benefits from elasticity), analytics (benefits from managed data services).
3. Third: Core applications with complex dependencies. Order processing, payment systems. By now, the team has migration experience, and the infrastructure is proven.
4. Last (or never): Applications with hard on-premises dependencies. Systems tightly coupled to on-premises hardware, mainframes, or on-premises-only software.

​

5.2 System Design for Modernization

​

Design Exercise 1: Strangler Fig for a Legacy Banking System

​

Design Exercise 2: Monolithic E-Commerce Platform Migration

​

Design Exercise 3: Multi-Year Cloud Migration Strategy

​

Design Exercise 4: Technical Debt Reduction Roadmap

​

5.3 Cross-Chapter Connections

​

Interview Questions — Comprehensive

​

Senior Engineer Level

​

Staff Engineer Level

​

Staff+ / Principal Engineer Level

​

Additional Interview Questions with Follow-Ups

​

Migration Deep Dives

​

Business Acumen Deep Dives

​

Cross-Cutting Deep Dives

​

Follow-Up Question Handling

​

Buying Time Gracefully

1. “That is a great question — let me think about the edge cases for a moment.” This is honest, signals that you are thinking deeply rather than just talking, and most interviewers will give you 10-15 seconds.
2. “Let me reason through this step by step.” Then start thinking out loud. The interviewer wants to see your reasoning process, not just the answer. Walk through the first principles.
3. “I want to make sure I give you a precise answer rather than a vague one. Can I take 30 seconds to organize my thoughts?” This is explicit and professional. No interviewer has ever penalized a candidate for asking for thinking time.
4. “Let me connect this back to what I know about [related concept].” This buys time while also showing that you think in terms of connections and patterns, not isolated facts.

​

Redirecting to Strength

• “I have not worked with that specific tool, but I have deep experience with the underlying pattern. The way I have implemented CDC is…” — redirects from a specific vendor to the general concept.
• “I would need to look up the exact configuration, but the architectural decision I would make is…” — redirects from implementation detail to design thinking, which is what Staff+ interviews care about.
• “In production, the way this manifests is…” — redirects from theory to practice, which is always more impressive.

​

Admitting Gaps with Confidence

• “I have not encountered that specific scenario in production, but based on first principles, I would expect…” Then reason from what you do know. This shows the interviewer that you can think through novel problems.
• “That is outside my direct experience. What I can tell you is how I would approach learning about it: I would look at [specific resources], talk to [specific people], and prototype [specific experiment].” This shows your learning process, which is more valuable than memorized facts.
• “I have a hypothesis but not production experience to validate it. My hypothesis is [X] because [reasoning]. I would want to validate this by [specific method] before committing to it.” This shows scientific thinking — hypothesis, reasoning, validation.

​

Professional Best Practices Checklist

​

Before Starting a Modernization Project

• Instrument the legacy system. Add structured logging, metrics, and tracing. You cannot modernize what you cannot observe.
• Map the domain. Conduct domain modeling sessions with stakeholders, product managers, and engineers. Identify bounded contexts.
• Quantify the pain. Measure: deployment frequency, lead time for changes, incident rate, onboarding time. These are your baseline metrics.
• Write the RFC. Document: the problem (with data), the proposed approach, alternatives considered, migration plan, success metrics, rollback plan.
• Secure executive sponsorship. A multi-quarter project without executive backing will be defunded at the first budget review.
• Assess team readiness. Do you have the skills for the target architecture? If not, invest in training before starting the migration.
• Plan the team topology. Which teams will own which services in the target state? Begin team restructuring early.
• Set up the routing layer. Deploy the API gateway or reverse proxy before extracting anything. This is your traffic control mechanism.

​

During a Modernization Project

• Ship incrementally. Every migration step should be deployable, measurable, and reversible.
• Shadow traffic before cutover. Run the new system in parallel with the old system and compare responses.
• Monitor both systems. Dual-stack observability: dashboards for the old system AND the new system. Track the delta.
• Decommission promptly. After a module is fully migrated, remove the old code within 2 weeks. Dead code creates confusion.
• Hold retrospectives. After each extraction, conduct a retro: what went well, what was painful, what would we do differently? Feed learnings into the next extraction.
• Communicate progress. Weekly update to stakeholders: what migrated this week, what is next, any blockers.
• Guard scope. “While we are migrating, let us also…” is the death sentence of migration projects. Migrate first. Improve after.
• Maintain the old system. The legacy system is still serving users. It still needs bug fixes and security patches. Do not let it rot during the migration.

​

After a Modernization Project

• Measure against baseline. Compare post-migration metrics to pre-migration baseline: deployment frequency, lead time, incident rate, developer satisfaction.
• Write the case study. Document what happened: timeline, costs, outcomes, lessons learned. This is institutional knowledge.
• Retire migration infrastructure. CDC pipelines, shadow traffic comparators, dual-write mechanisms — these are temporary. Remove them.
• Update documentation. Architecture diagrams, runbooks, on-call procedures, onboarding guides — all must reflect the new reality.
• Celebrate. Multi-quarter migrations are exhausting. Acknowledge the team’s effort publicly.

​

When Things Go Wrong

• Rollback immediately. If error rates spike after a traffic shift, roll back to the old system. Do not debug in production with users affected.
• Investigate after rollback. Once traffic is back on the old system, analyze the failure. Shadow traffic should have caught this — why did it not?
• Communicate transparently. Tell stakeholders what happened, what the impact was, and what you are doing to prevent recurrence.
• Update the playbook. Every failure teaches something. Add it to the migration playbook so the next extraction does not hit the same issue.
• Resist the urge to blame the new system. The failure might be in the routing layer, the monitoring, the data sync, or the test coverage. Investigate the root cause, not the symptom.

​

Above and Beyond

​

Advanced Techniques

​

Cross-Domain Connections

​

Emerging Trends

​

Recommended Reading

​

Beginner

• “Working Effectively with Legacy Code” by Michael Feathers. The definitive guide to working with code that has no tests. Introduces characterization tests, seams, and the dependency-breaking techniques that make legacy code testable. If you read one book on legacy systems, make it this one.
• “The Phoenix Project” by Gene Kim, Kevin Behr, and George Spafford. A novel about a manufacturing plant methodology applied to IT. Accessible introduction to DevOps thinking, bottleneck theory, and the organizational dynamics of technical transformation. Read it before starting any modernization project.
• Martin Fowler’s “Strangler Fig Application” essay (martinfowler.com). The original description of the pattern. Short, clear, and free. The starting point for understanding incremental migration.

​

Intermediate

• “Monolith to Microservices” by Sam Newman. The practical guide to decomposition. Covers the Strangler Fig pattern, database decomposition, and the organizational implications of microservices — all with real examples and honest trade-off analysis.
• “Team Topologies” by Matthew Skelton and Manuel Pais. How to structure engineering teams for fast flow of change. The inverse Conway maneuver, the four team types, and interaction modes. Essential for understanding why modernization is an organizational change, not just a technical one.
• “An Elegant Puzzle” by Will Larson. Systems thinking applied to engineering management. Covers organizational design, technical strategy, and the relationship between team structure and system architecture. Bridges the gap between technical and organizational modernization.

​

Advanced

• “Designing Data-Intensive Applications” by Martin Kleppmann. The gold standard for understanding distributed data systems, replication, partitioning, and consistency models. Essential background for database decomposition and data migration strategies.
• “Technology Strategy Patterns” by Eben Hewitt. How to create and communicate technology strategy at the organizational level. Covers technology radar, investment portfolio management, and the strategic thinking frameworks that Staff+ and Principal engineers need.
• “Accelerate” by Nicole Forsgren, Jez Humble, and Gene Kim. The research behind DORA metrics. Proves the connection between deployment frequency, lead time, and business outcomes. Essential for making the data-driven case for modernization investment.

​

Self-Assessment

​

Key Takeaways

1. A legacy system is defined by its modifiability, not its age. A system with no tests, no documentation, and concentrated knowledge is legacy regardless of when it was built.
2. The Strangler Fig pattern is the default modernization strategy because it delivers value incrementally, allows rollback at every step, and avoids the 70%+ failure rate of big-bang rewrites.
3. Database decomposition is the hardest part of microservices migration. Splitting code is easy. Splitting data requires CDC, eventual consistency, saga patterns, and reconciliation — plan for this to take 3-5x longer than the code extraction.
4. Technical debt is a strategic tool, not just a liability. Deliberate, prudent debt (taking shortcuts to hit a market window with a plan to pay back) is fundamentally different from reckless, inadvertent debt (writing bad code because you did not know better).
5. Build what differentiates you. Buy everything else. But always calculate the TCO including hidden costs on both sides, and always have an exit strategy for vendor dependencies.
6. Staff+ engineers connect technical decisions to business outcomes. The difference between “we refactored the caching layer” and “we reduced checkout latency by 40%, which projects a 3% improvement in conversion rate” is the difference between a senior and a Staff+ engineer.
7. Conway’s Law is real and inescapable. Your architecture will mirror your organizational structure. If you want to change the architecture, you must also change the organization — preferably before or simultaneously, not after.

​

Confidence Rating Guide

​

Senior Interview Deep-Dives: Scenario-Driven Questions