Recover a legacy system's architecture before you change it — package the codebase context, explain the current structure, surface the risks and seams, then document the recovered architecture.
Greenfield architecture design and architecture recovery are opposite jobs, and using the first for the second is how modernization goes wrong. A legacy system already has an architecture — it's just undocumented, scattered across the code, and half-understood. Designing a 'new' architecture for it skips the expensive part: figuring out what's actually there, what depends on what, and where change is safe versus where it cascades. Recovery is the deliberate version — understand the current structure, separate what the code shows from what you're assuming, and find the seams — so modernization decisions rest on the real system instead of a guess about it.
Each step uses an existing NewPrompt tool, pre-filled by a matching resource. Open the resource to read it, or jump straight into the tool with the inputs ready.
Package the codebase context
Set up what the AI needs to know about the existing codebase — its stack, structure, and conventions — so it reasons from the real system instead of guessing at it.
Explain the current architecture
Have the AI explain the system's actual shape — modules, boundaries, dependencies, and data flows — keeping what the code shows separate from what it infers.
Find the legacy risks and seams
Identify the risky coupling and fragile dependencies, and the seams where modernization can start safely — the places change is cheap versus where it cascades.
Document the recovered architecture
Write up the recovered architecture as a document the modernization works from — structure, dependencies, risks, and the open questions still to resolve.
The existing system's architecture recovered and documented — its current structure explained, the risks and modernization seams identified, and a recovered-architecture document the team works from — so modernization decisions rest on the real system instead of a guess about it.
That workflow designs a new architecture from trade-offs — greenfield, deciding structure that doesn't exist yet. This one recovers the architecture already living in a legacy system: what modules exist, how they connect, and where change is risky. One invents structure; this uncovers and documents it.
No. It produces understanding and a recovered-architecture document — observed facts separated from inference, with the open questions named. The actual refactoring and modernization are separate workflows that build on what this recovers.
A recovered-architecture document written in step 4 — the current structure explained, dependencies mapped, legacy risks and safe modernization seams named, and the open questions still to resolve. It's the artifact your modernization or refactoring team works from, not a change to the code itself.
The existing codebase and enough context for the AI to reason from the real system: its stack, structure, and conventions, packaged in step 1 with the project-context-builder. Without that project context profile the AI guesses at the architecture instead of reading it, and the recovery is unreliable.
Work the four steps in order in your own AI tool: package the codebase context, have the AI explain the current architecture, find the legacy risks and modernization seams, then document the recovered architecture. NewPrompt supplies each step's prompt and links; you run them and confirm each claim against the real system.
Check the explanation against the code yourself — this workflow keeps observed facts marked apart from inference in step 2, so scrutinize the inferred claims first. Where a module boundary or dependency looks wrong, re-run the explanation prompt with that file included, and log unresolved gaps as open questions in the step-4 document.
Complete build journeys that include this workflow as a stage.
The full path to taming an inherited codebase — understand it, document its architecture, pin its behavior with tests, then refactor, modernize, review, speed up, and ship it without breaking what works.
Update old, risky code you didn't write — safely — by understanding and pinning its behavior in tests before you change a single line.
Get up to speed on an unfamiliar codebase in an afternoon — ground the AI in the project, have it explain the hard parts, and keep what you learn.
Design a system's architecture on its real trade-offs instead of a confident diagram — put the model in an architect's seat, work the decisions one at a time, and write down the why.