30. Migrating from UML / ArchiMate tools
Most readers of this book won’t have used UML, ArchiMate, or other enterprise-architecture modeling suites. If you haven’t, skip this chapter; it’s a translation guide, not a tutorial.
If you have used those tools — and especially if you’re trying to migrate an existing model — this chapter maps your vocabulary onto ArchLang’s. The mappings aren’t always one-to-one. A few EA concepts have no ArchLang equivalent because the language deliberately rejected them. A few ArchLang concepts have no clean EA equivalent because the language explicitly added them.
There is no import button
Section titled “There is no import button”Set the expectation first, because it’s the one most people get wrong: ArchLang cannot import your EA diagrams. There is no converter for proprietary model files, no Structurizr DSL importer, no ArchiMate XML reader, no C4 diagram parser. This isn’t a missing feature on a roadmap — it’s structural.
The reason is the core inversion (Chapter 7): ArchLang edges are derived from processes, not drawn. In your EA tool you placed two boxes and dragged an arrow labeled “Used-By” between them. That arrow is a drawing. ArchLang has no place to put it — a dependency exists only because some process step says Caller > Callee.Interface. There is nothing to mechanically translate a drawn arrow into, because the arrow was never the source of truth; it was a picture of one.
So migration is a manual remodel, not a conversion. You re-express the meaning of the old model in ArchLang’s terms — and the meaning, for the edges, lives in your sequence and activity diagrams, not your component diagrams. Trying to mechanically port boxes-and-lines produces a model that looks like the old one and means nothing: a pile of modules with arrows that no process backs.
Rule. Don’t reproduce drawn edges. Re-model by domain in two passes — first the modules (the cast), then the processes (the story) — and let the dependency arrows fall out of the process steps. Architecture is a description you write, not a drawing you port. If an arrow in the old diagram has no process behind it, it doesn’t survive the move, and that’s correct.
Why the mappings aren’t clean
Section titled “Why the mappings aren’t clean”The traditional EA tools were built on a few premises ArchLang doesn’t share:
- Diagrams are the primary artifact. Modelers draw boxes and arrows; the model is the picture. ArchLang inverts this: the model is text, and diagrams are derived projections (Chapter 14).
- The ontology is large and fixed. ArchiMate alone has 50+ concept types (Business Actor, Business Service, Application Function, Technology Process, …). ArchLang has four primitives (module, interface, process, view) plus user-defined types. The ontology is small and extensible.
- TO-BE vs AS-IS is explicit. Modelers carry flags or duplicate elements to distinguish current from proposed state. ArchLang doesn’t — Git branches are the future state (Chapter 14 again).
- Stereotypes / archetypes / templates as a separate facility. Multiple parallel mechanisms for “this thing is a type of.” ArchLang collapses them into one: type form templates (Chapter 15).
What follows tells you how to express your existing concepts, what to drop, and what’s new.
Core element mapping
Section titled “Core element mapping”| EA concept | ArchLang |
|---|---|
| Application component | service (or any custom subtype) |
| Application service | interface on a service |
| Business component | module (often system for higher-level grouping) |
| Business service | interface on a business component module |
| Business actor / role | user (stdlib module type) |
| Business process | process |
| Technology component | service, database, gateway. A broker/queue is usually transport, not a node — model the logical call and attach the broker as an aspect (Chapter 26). Make it a message_broker module only if your services call its admin API. |
| Technology service | interface |
| Data object / artifact | A field on the module that produces or owns it (not a separate primitive) |
| Capability | A surface on a module, or a custom surface type |
| Stereotype | A type declaration (type service payment_service { ... }) |
| Archetype | Same as stereotype — a type declaration |
| Template | Same as stereotype — a type declaration |
The first observation: ArchiMate’s three columns (Business / Application / Technology) collapse into ArchLang’s one tree. Layers in ArchiMate become aspects in ArchLang (aspect layer: business, aspect layer: application, …), and views slice by layer when needed.
Relationships
Section titled “Relationships”| EA relationship | ArchLang |
|---|---|
| Composition (whole-part) | Nesting (service X { component Y { ... } }) or in clause |
| Aggregation | Less common; usually nesting works |
| Realization | The interface IS the realization. Don’t model it separately. |
| Assignment (actor to process) | Process step with the actor as caller |
| Used-by | Process step (caller > callee.interface) |
| Triggering | Process step (sync or async — the callee’s interface type decides) |
| Flow | Process step |
| Specialization | Subtype in the type system |
| Association | If it’s not one of the above, you probably don’t need it |
The biggest jump: most EA relationship types collapse into “a process step” or “containment.” The reason: process steps capture causality; containment captures ownership; the rest is detail.
Mindset shift. EA tools encourage drawing relationships first. You draw an arrow between two components and label it “Used-By” or “Triggers.” ArchLang inverts this — you write process steps first, and the arrows are derived. If you find yourself wanting to add a relationship that isn’t a process step or containment, ask whether the underlying fact is causality (use a process), ownership (use containment), or classification (use an aspect or type). Almost everything reduces to those three.
What doesn’t transfer
Section titled “What doesn’t transfer”Several EA concepts don’t have an ArchLang equivalent. This isn’t oversight — they were deliberately excluded.
TO-BE / AS-IS markers. ArchLang doesn’t have a status field on declarations. Branches in git play that role. Your “current state” model lives on main; your “proposed state” model lives on a feature branch. The structural diff (Chapter 14) shows the delta.
For migration: if your EA model has TO-BE artifacts, drop them. Use branches.
New / changed / existing flags. Same as above. The diff engine derives these from comparing two model snapshots.
Multiple parallel “views” of the same element. In a drawing-first tool, the same physical service can appear in five different diagrams, each with different connections drawn. In ArchLang, the model is one; views are projections of that one model. You can have five views of a service; they’re all reading from the same canonical record.
Free-text “stereotypes” stuck onto elements. EA tools let you tag any element with arbitrary stereotype strings. ArchLang requires the stereotype to be a declared type. The benefit: type-level rules (required blanks, cascade behavior) attach to the stereotype. The cost: you can’t just slap a label and move on.
For migration: figure out what your stereotypes actually mean and write them as type declarations.
Constraint annotations as free text. EA tools let you write OCL constraints in notes that humans read and tools ignore. ArchLang requires constraints to be enforceable — required blanks (Chapter 17) and validation rules (Chapter 28). The model encodes only what the validator can check.
What’s new
Section titled “What’s new”Several ArchLang ideas don’t have an EA equivalent. They earn their own learning curve.
Stable IDs. EA tools use names as identity. ArchLang uses opaque IDs (Chapter 13) so renames don’t break references. There’s no equivalent in the drawing-first tools — renaming there silently breaks every diagram that referenced the old name.
The form-template type model. EA tools have stereotypes; ArchLang has form templates that stamp content. The difference: stereotypes are tags. Form templates are requirements that propagate — a stereotype telling instances “you must fill in team” is enforced at parse time. The nearest EA equivalent is a “tagged value with mandatory=true” but the propagation isn’t there.
Two compose-able propagation mechanisms. Template stamping (mechanism A) plus structural cascade (mechanism B) — together they let a single aspect or field set on a parent module reach every nested element. EA tools don’t have an equivalent; they require you to set the value on every element explicitly. See Chapter 18.
Git as the system of record. EA tools store models in proprietary files (or Oracle/SQL Server back-ends). ArchLang stores .arch files in your repo, next to the code they describe. The model is reviewable in pull requests, branchable, mergeable. There’s no migration import/export to do — once it’s in .arch files, git is the tool.
A migration approach
Section titled “A migration approach”For an existing EA model with ~500 elements:
Phase 0 — Decide what to keep. Most EA models accumulate cruft over years. Identify the core 50-100 elements that represent the actual current architecture. Set aside the rest.
Phase 1 — Define your types first. Look at the stereotypes in use. Decide which ones map to existing stdlib types (service, database, external_system, user, frontend) and which need custom types (Chapter 29). Write types.arch first.
Phase 2 — Re-model the modules, in isolation (pass one). Go module by module. Declare each in .arch files with its type, name, team, and key aspects, and add its interfaces — but do not think about connections yet. Don’t port a single arrow. This is the first of the two-pass flow (best practices): describe the cast before the story. Bare modules are fine; you’re capturing what each thing is, not how it wires up.
Phase 3 — Re-model the processes (pass two). Now the connections. Walk your old sequence and activity diagrams — the ones that encode real causality and ordering — and re-express each as a process. The dependency arrows emerge from the process steps; you never draw them. Crucially, your component diagrams (the boxes-and-lines pictures) are not the input here — an arrow there with no behavior behind it has nothing to become, and shouldn’t survive the move.
Phase 4 — Add views. Recreate the saved diagrams as view declarations, using show/hide and group by @@…, style for emphasis/colour, and a table/matrix/flow representation where the old view was a table or a sequence/flow diagram.
Phase 5 — Add validation. Identify the rules you wished the old tool had enforced — required runbook URLs, required compliance aspects, required teams. Encode them as required blanks on your types.
By the end you’ll have ~half the source you had before (ArchLang is more compact), zero broken diagrams, and the ability to review architecture in pull requests for the first time.
What to set realistic expectations about
Section titled “What to set realistic expectations about”- Initial diagrams will look different. ArchLang’s layouts (ELK, Dagre) are auto-generated; you can’t pixel-place nodes. The first time you generate a diagram from a migrated model, it’ll look unfamiliar. Within a week most people prefer the auto-layout because it’s consistent.
- You’ll lose some EA-suite features. Calendar-based forecasting, gap analysis tools, ArchiMate-specific viewpoint frameworks — those don’t exist in ArchLang. If they’re load-bearing in your organization, evaluate whether they’re worth keeping in parallel (the old suite for those reports, ArchLang for the architecture).
- Custom tool scripts won’t port. They were written against your EA suite’s scripting API. The equivalent in ArchLang is
@archlang/engine(Chapter 24) — easier to write, but the rewrite cost is real. - The vocabulary takes weeks to settle. Teams used to “Application Service” + “Business Process” + “Information Object” will write things in ArchLang’s vocabulary awkwardly at first. The book chapters speed the transition; resist the urge to recreate the EA vocabulary literally as user-defined types.
Summary
Section titled “Summary”- There is no import button — no proprietary-model / Structurizr / ArchiMate / C4 converter. Migration is a manual remodel because edges derive from processes, not drawings.
- Don’t reproduce drawn edges; re-model by domain in two passes (modules, then processes) and let arrows fall out of process steps. Architecture is a description, not a drawing tool.
- Most EA concepts map to module / interface / process / view, with stereotypes becoming types.
- ArchiMate layers become aspects; views slice by layer. A broker is transport (an aspect), not a node.
- TO-BE / AS-IS markers are replaced by git branches.
- Stable IDs solve the rename-breaks-everything problem the drawing-first tools never solved.
- Form templates plus structural cascade replace stereotypes-with-tagged-values plus manual per-element configuration.
- The migration approach: types first, then modules in isolation, then processes, then views, then validation.
End of Part VI
Section titled “End of Part VI”That’s the book — twenty-nine chapters from the foreword’s three commitments through six worked designs. The appendices (Grammar, Keywords, Stdlib Types, Cheatsheet) are dense lookup once you know what you’re looking for.
If you read every chapter in order, you now have the language, the metamodel, the tooling, and a sense of how real systems get modeled. The next step is your own .arch file — and the loop the editor extensions give you, where you save and the diagram updates. That loop is where the language earns its keep.