Run an architecture review before you rewrite the app

Most rewrites start with a real pain: releases are slow, bugs keep returning, and nobody trusts the current system. The mistake is assuming the only honest fix is to start over.

An architecture review gives the team a sharper question: what exactly is making the system expensive to change?

Map the system first

Start with a lightweight map of the product, not the repository tree. Identify the major user journeys, the services or modules that support them, and the data that moves between them.

Useful review artifacts:

• A dependency map of the most important modules
• A deployment and environment map
• A list of business-critical flows
• A list of slow or risky release steps

The goal is not a beautiful diagram. The goal is shared language.

Separate symptoms from constraints

Slow delivery can come from many places: unclear ownership, weak tests, overloaded database tables, manual deployments, or a framework that no longer fits the product.

Before proposing a rewrite, classify each issue:

• Product uncertainty
• Code structure
• Data model
• Infrastructure
• Team process
• Security or compliance

That classification usually reveals that a smaller migration will solve more than a dramatic restart.

Score migration paths

Every option should be judged by user impact, operational risk, cost, and reversibility. A staged migration with visible checkpoints is usually easier to fund and easier to trust.

type ReviewScore = {
  userImpact: "low" | "medium" | "high";
  operationalRisk: "low" | "medium" | "high";
  reversible: boolean;
};
 
export function shouldStartSmall(score: ReviewScore) {
  return score.operationalRisk === "high" || score.reversible === false;
}

End with a decision document

A strong review ends with the next three moves, not a vague recommendation. Include the tradeoffs, the risks you are accepting, and the signals that would change the plan.