Diagrams vs Models
One of the most important concepts in Farkitect is the distinction between a model and a diagram. Getting this right changes how you think about organizing your work and prevents a class of mistakes that plague users of simpler drawing tools.
The Model is the Truth
Section titled “The Model is the Truth”Your model is the collection of all elements, relationships, and property values in your project. It lives in packages in the Explorer. Every element you create — whether from the Palette, the Explorer context menu, or by importing a .farki file — becomes part of the model.
The model is structured data. It has types, properties, constraints, and relationships. It’s queryable, exportable, and shareable. It exists independently of any visual representation.
A Diagram is a View
Section titled “A Diagram is a View”A diagram is a visual arrangement of some elements from the model. It shows a subset of the model on a Canvas with positions, sizes, edge routes, and formatting. But the diagram doesn’t contain the elements — it references them.
This means:
-
One element can appear on many diagrams. An Application Component called “FQ Vessels” might appear on an Application Cooperation diagram, an Infrastructure diagram, and a Deployment diagram. It’s the same model element shown in three different visual contexts.
-
Removing an element from a diagram doesn’t delete it. Pressing Delete on a Canvas node removes it from that diagram. The element still exists in the model (in the Explorer) and still appears on any other diagrams where it’s placed.
-
Deleting an element from the model removes it everywhere. Using Ctrl+Delete / Cmd+Delete (or deleting from the Explorer) removes the element from the model entirely — and from every diagram where it appeared.
Why This Matters
Section titled “Why This Matters”For organizing your work
Section titled “For organizing your work”You can create multiple diagrams that show different perspectives on the same model. A high-level overview diagram might show Farquind’s major applications as large boxes. A detail diagram might zoom into one of those applications and show its internal components. Both diagrams reference the same underlying model elements.
This means your model has one source of truth. When you change an element’s name or properties, the change appears everywhere — on every diagram, in every catalog and board, and in every export.
Diagrams are one kind of view. Catalogs (tables) and boards (Kanban) are two more — each a different projection of the same underlying elements.
For avoiding duplication
Section titled “For avoiding duplication”In a simple drawing tool, if you want the same box on two diagrams, you draw it twice. Now you have two copies with no connection between them. Change one, and the other is stale. In Farkitect, you place the same element on both diagrams. There’s only one element in the model, shown in two places.
For exports and catalogs
Section titled “For exports and catalogs”Catalogs and exports work with the model, not with diagrams. A catalog shows elements from a package — regardless of which diagrams they appear on. An export captures the full model structure. Elements that exist in the model but don’t appear on any diagram are still exported and cataloged.
For collaboration
Section titled “For collaboration”When a team member adds an element to the model, everyone can see it in the Explorer and add it to their own diagrams. Changes to property values are visible in real time across all views — diagrams, catalogs, boards, and the Properties panel.
The Analogy
Section titled “The Analogy”Think of the model as a database and diagrams as dashboard views. The database holds the data; the dashboards present different slices of it. You can add, remove, or rearrange widgets on a dashboard without changing the underlying data. But when the data changes, every dashboard that references it reflects the change.
In Practice
Section titled “In Practice”| Action | What happens to the model | What happens to diagrams |
|---|---|---|
| Drag element from Palette to Canvas | Element created in model + placed on this diagram | Node appears on this diagram |
| Drag element from Explorer to Canvas | No model change (element already exists) | Node appears on this diagram |
| Press Delete on a Canvas node | No model change | Node removed from this diagram only |
| Press Ctrl+Delete on a Canvas node | Element deleted from model | Node removed from all diagrams |
| Delete element from Explorer | Element deleted from model | Node removed from all diagrams |
| Rename element in Properties panel | Element renamed in model | Name updates on all diagrams |
| Change a property value | Value updated in model | Visible on all diagrams showing that property |
| Move a node on the Canvas | No model change | Position changes on this diagram only |
The left column (model changes) is global. The right column (diagram changes) is local to the specific diagram.
Key Takeaway
Section titled “Key Takeaway”When you’re working in Farkitect, always think about whether you’re changing the model or changing the diagram. Model changes ripple everywhere. Diagram changes affect only what you see in front of you.
This separation is what makes Farkitect a modeling tool rather than a drawing tool — and it’s what makes your models useful as structured, queryable, exportable data rather than just pictures.