Migrating Legacy Microservices to Modern Java and TypeScript

# For Maven projects: visualize the dependency tree
mvn dependency:tree -Dverbose | grep -E "(INFO|WARN)" > dep-tree.txt

# For Node.js microservices: check for outdated dependencies

// Capture response time metrics using a Node.js middleware
import { Request, Response, NextFunction } from 'express';
import { Histogram } from 'prom-client';

const httpDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  labelNames: ['method', 'route', 'status_code'],
  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
});

export function metricsMiddleware(req: Request, res: Response, next: NextFunction) {
  const end = httpDuration.startTimer();
  res.on('finish', () => {
    end({ method: req.method, route: req.route?.path ?? req.path, status_code: res.statusCode });
  });
  next();
}
Phase 1: Containerize Without Changing Logic

# Stage 1: Build
FROM maven:3.9.4-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
# Cache dependencies separately from source code
RUN mvn dependency:go-offline -q
COPY src ./src
RUN mvn clean package -DskipTests

# Stage 2: Runtime
FROM eclipse-temurin:17-jre-jammy AS runtime
WORKDIR /app

# Run as non-root user
RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
USER appuser

COPY --from=build /app/target/*.jar app.jar

# JVM tuning for containerized environments
ENV JAVA_OPTS="-XX:+UseContainerSupport \
               -XX:MaxRAMPercentage=75.0 \
               -XX:+UseG1GC \
               -XX:+HeapDumpOnOutOfMemoryError"

EXPOSE 8080

apiVersion: apps/v1
kind: Deployment
metadata:
  name: document-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: document-service
  template:
    spec:
      containers:
        - name: document-service
          image: registry.internal/document-service:1.0.0
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "1000m"
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            initialDelaySeconds: 60
            periodSeconds: 20
          env:
            - name: SPRING_DATASOURCE_URL
              valueFrom:
                secretKeyRef:
                  name: db-credentials

upstream legacy_document_service {
    server legacy-docs:8080;
}

upstream new_document_service {
    server new-docs:8080;
}

server {
    location ~ ^/api/v1/documents/(.*)$ {
        # Legacy routes still served by old service
        proxy_pass http://legacy_document_service;
    }

    location ~ ^/api/v2/documents/(.*)$ {
        # New endpoints served by migrated service
        proxy_pass http://new_document_service;
    }
    
    # Feature-flagged shadow routing for validation
    location ~ ^/api/v1/documents/generate$ {
        # Route 5% of traffic to new service for comparison
        set $upstream legacy_document_service;
        if ($request_id ~* "^[0-4]") {
            set $upstream new_document_service;
        }
        proxy_pass http://$upstream;
    }

// Shadow mode middleware for validation
async function shadowTest(req: Request, res: Response, next: NextFunction) {
  // Send request to legacy system and return its response
  const legacyResponse = await axios(buildLegacyRequest(req));

  // Asynchronously compare with new service (fire-and-forget)
  shadowCompare(req, legacyResponse).catch((err) =>
    logger.warn('Shadow test failed', { path: req.path, error: err.message })
  );

  // Return legacy response to client
  res.status(legacyResponse.status).json(legacyResponse.data);
}

async function shadowCompare(req: Request, legacyResponse: AxiosResponse) {
  const newResponse = await axios(buildNewServiceRequest(req));

  const match =
    legacyResponse.status === newResponse.status &&
    isEquivalentResponse(legacyResponse.data, newResponse.data);

  await metrics.record({
    endpoint: req.path,
    match,
    legacyDuration: legacyResponse.headers['x-response-time'],
    newDuration: newResponse.headers['x-response-time'],
  });

// Before: Direct shared DB access
const user = await db.query('SELECT * FROM shared.users WHERE id = $1', [userId]);

// After: Routed through ACL
import { UserRepository } from '@domain/users/repository';
const user = await userRepository.findById(userId);

-- V2.1.3__extract_document_metadata_to_service_schema.sql
-- Create the new schema owned by document-service
CREATE SCHEMA IF NOT EXISTS document_service;

-- Copy data (non-destructive)
CREATE TABLE document_service.metadata AS
SELECT id, document_id, created_at, created_by, file_size
FROM shared.document_metadata;

-- Add constraints to new table
ALTER TABLE document_service.metadata
  ADD CONSTRAINT pk_metadata PRIMARY KEY (id),
  ADD CONSTRAINT fk_document FOREIGN KEY (document_id)
      REFERENCES document_service.documents(id);

-- Dual-write trigger during migration window (dropped after cutover)
CREATE OR REPLACE FUNCTION sync_metadata_to_new_schema()
RETURNS TRIGGER AS $$
BEGIN
    INSERT INTO document_service.metadata
    VALUES (NEW.id, NEW.document_id, NEW.created_at, NEW.created_by, NEW.file_size)
    ON CONFLICT (id) DO UPDATE
    SET file_size = EXCLUDED.file_size;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER sync_metadata
AFTER INSERT OR UPDATE ON shared.document_metadata

Quote Request → QuoteService → [HTTP] → PricingService → [HTTP] → EligibilityService

// QuoteService publishes an event and returns immediately
async function initiateQuote(request: QuoteRequest): Promise<QuoteAcknowledgement> {
  const quoteId = generateQuoteId();

  await kafkaProducer.send({
    topic: 'quote.initiated',
    messages: [{
      key: quoteId,
      value: JSON.stringify({ quoteId, ...request, timestamp: Date.now() }),
    }],
  });

  // Return immediately — processing is async
  return { quoteId, status: 'processing', estimatedCompletion: Date.now() + 3000 };
}

// PricingService subscribes to quote.initiated and publishes quote.priced
kafkaConsumer.on('quote.initiated', async (event) => {
  const price = await calculatePrice(event);
  await kafkaProducer.send({
    topic: 'quote.priced',
    messages: [{ key: event.quoteId, value: JSON.stringify({ ...event, price }) }],
  });
});

// EligibilityService subscribes to quote.priced
kafkaConsumer.on('quote.priced', async (event) => {
  const eligibility = await checkEligibility(event);
  await kafkaProducer.send({
    topic: 'quote.ready',
    messages: [{ key: event.quoteId, value: JSON.stringify({ ...event, eligibility }) }],
  });