How to import an architecture generated from source code
Import an architecture JSON produced by Archify, correct anything it was unsure about, and understand what happens when you import an updated version later.
When this is useful
- The documented architecture and the real one have drifted apart and you want to close the gap mechanically.
- You want architecture documentation that can be regenerated each release instead of maintained by hand.
- A new joiner needs an accurate picture of a codebase nobody has drawn.
Before you start
- An `.architecture.json` file produced by Archify against your repository.
- A diagram page to import onto. A fresh page is easiest for a first import.
Step 1: Open the import wizard
The Archify import lives in the Diagram menu.
Diagram ▸ Import Archify (.json)
Step 2: Read the review screen before importing
The review screen counts what the document contains — components, connections and boundaries — along with how many claims carry a source and how many component roles the analyser was unsure about.
The unsure count is the honest one. Read it before you import rather than after.
Step 3: Override the roles it got wrong
Where the analyser guessed a component's role, change it in the review table. Your catalogue is the authority; the imported type is a suggestion, and an overridden row is recorded as your choice rather than silently replaced next time.
Step 4: Import, and re-import later
Importing places the components on the page, grouped inside their boundaries.
Importing the same document again merges rather than duplicates: shapes you moved stay where you put them unless you explicitly choose to take the document's layout, and anything the codebase no longer contains is counted and reported rather than deleted. Removing something from your architecture stays your decision.
Diagram ▸ Import Archify (.json)
What happens next
If the document carried source references, each imported shape can be traced back to the file and lines behind it — that is a separate guide.
The export goes the other way through Diagram ▸ Export ▸ Archify (.json), so the model is not trapped in one tool.
Example
A service repository imported at an older commit, then re-imported at HEAD after a new service was added: the new component appeared inside the right boundary, the hand-adjusted layout survived, and a retired component was reported as no longer present rather than removed.
Tips
- Do the role overrides on the first import. They are recorded, so later imports do not re-ask.
- Shapes you drew yourself are untouched by a merge — matching only engages for shapes an import created.
Limitations
- No import preserves everything. Concepts Archify expresses that have no equivalent here cannot survive the trip, which is why the wizard reports what it was unsure of.
- Source-level evidence only arrives if the document contains it; not every Archify document does.